@shipengine/connect-carrier-api 2.12.13 → 2.12.15

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"
@@ -3192,6 +3267,9 @@
               "$ref": "#/components/schemas/ServicePointFeature"
             },
             "nullable": true
+          },
+          "type": {
+            "$ref": "#/components/schemas/ServicePointLocationType"
           }
         },
         "additionalProperties": false
@@ -3224,6 +3302,13 @@
         ],
         "type": "string"
       },
+      "ServicePointLocationType": {
+        "enum": [
+          "pudo",
+          "locker"
+        ],
+        "type": "string"
+      },
       "ServicePointResponseAddress": {
         "required": [
           "postal_code",
@@ -3338,6 +3423,31 @@
             "type": "string",
             "description": "The code associated with the package type",
             "nullable": true
+          },
+          "label_messages": {
+            "$ref": "#/components/schemas/LabelMessage"
+          },
+          "customs": {
+            "$ref": "#/components/schemas/Customs"
+          },
+          "insured_value": {
+            "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 insured value of this package.",
+            "nullable": true
           }
         },
         "additionalProperties": false,
@@ -3377,6 +3487,9 @@
           },
           "advanced_options": {
             "$ref": "#/components/schemas/AdvancedOptions"
+          },
+          "pickup_location": {
+            "$ref": "#/components/schemas/PudoLocation"
           }
         },
         "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/app/metadata/service-point-location-type.ts

@@ -0,0 +1,10 @@
+import Joi from 'joi';
+
+export enum ServicePointLocationTypeEnum {
+  PUDO = 'pudo',
+  Locker = 'locker',
+}
+
+export const ServicePointLocationTypeEnumSchema = Joi.string().valid(
+  ...Object.values(ServicePointLocationTypeEnum),
+);

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/service-points/service-point-schema.ts

@@ -1,5 +1,6 @@
 import Joi from 'joi';
 import { ServicePointFeaturesEnumSchema } from '../../app/metadata/service-point-feature';
+import { ServicePointLocationTypeEnumSchema } from '../../app/metadata/service-point-location-type';
 import { ServicePointResponseAddressSchema } from './service-point-response-address-schema';
 import { WeeklyHoursOfOperationSchema } from './weekly-hours-of-operation-schema';
 
@@ -8,4 +9,5 @@ export const ServicePointSchema = Joi.object({
   address: ServicePointResponseAddressSchema.required(),
   hours_of_operation: WeeklyHoursOfOperationSchema.required(),
   features: Joi.array().items(ServicePointFeaturesEnumSchema).optional(),
+  type: ServicePointLocationTypeEnumSchema.optional(),
 });

package/src/models/service-points/service-point.ts

@@ -1,4 +1,5 @@
 import { ServicePointFeaturesEnum } from '../../app/metadata/service-point-feature';
+import { ServicePointLocationTypeEnum } from '../../app/metadata/service-point-location-type';
 import { ServicePointResponseAddress } from './service-point-response-address';
 import { WeeklyHoursOfOperation } from './weekly-hours-of-operation';
 
@@ -12,4 +13,6 @@ export class ServicePoint {
   hours_of_operation!: WeeklyHoursOfOperation;
   /** @description Features supported by the service point */
   features?: ServicePointFeaturesEnum[];
+  /** @description Location type like PUDOs, parcelshops, postoffices, lockers, retailers own stores etc. */
+  type?: ServicePointLocationTypeEnum;
 }

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/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/**/*"],