@shipengine/connect-carrier-api 2.1.18 → 2.1.22

package/spec.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "ShipEngine Connect Carrier API",
     "description": "This API specification describes the canonical ShipEngine Carrier API connector module. A module which implements one or more endpoints from this specification can be integrated with the ShipEngine Carrier Platform.",
-    "version": "1.14.10"
+    "version": "1.14.13"
   },
   "paths": {
     "/Register": {
@@ -1178,6 +1178,25 @@
         "additionalProperties": { },
         "description": "This is a schemaless object. It is for open ended customizations unique to particular carriers. The documented\r\nkeys are some common options shared by many carriers, but are not definitive. Advanced options you support will\r\nbe defined in ShipEngine. If the field is absent it should be interpreted as the default value for any\r\napplicable options, e.g. false for booleans."
       },
+      "Authorization": {
+        "type": "object",
+        "properties": {
+          "access_token": {
+            "type": "string",
+            "description": "The access token used to authorize the request",
+            "nullable": true
+          },
+          "connection_context": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Optional - any additional information required to authorize the request",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false
+      },
       "BadRequestResponse": {
         "type": "object",
         "allOf": [
@@ -1196,6 +1215,9 @@
             "description": "The transaction ID uniquely represents this request. If the request is retried then this transaction ID will be the same. You should only perform the requested action once per given transaction ID.",
             "format": "uuid"
           },
+          "authorization": {
+            "$ref": "#/components/schemas/Authorization"
+          },
           "metadata": {
             "type": "object",
             "additionalProperties": { },
@@ -3449,6 +3471,14 @@
             },
             "description": "A list of errors preventing this label from being voided. If no errors are returned the void is considered\r\nsuccessful. If any errors are returned the void is considered failed.",
             "nullable": true
+          },
+          "billing_line_items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/BillingLineItem"
+            },
+            "description": "Individual Billing Line items which remain after voiding the label, e.g. a cancellation fee.",
+            "nullable": true
           }
         },
         "additionalProperties": false,

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

@@ -9,6 +9,8 @@ import {
   TrackingRequest,
   CancelNotificationRequest,
   CreateNotificationRequest,
+  ValidateInboundDataRequest,
+  NormalizeTrackingDataRequest,
 } from '../requests';
 
 import {
@@ -22,6 +24,8 @@ import {
   TrackingResponse,
   CancelNotificationResponse,
   CreateNotificationResponse,
+  ValidateInboundDataResponse,
+  NormalizeTrackingDataResponse,
 } from '../responses';
 
 import { CarrierAppMetadata } from './metadata/carrier-app-metadata';
@@ -101,4 +105,18 @@ export interface CarrierAppDefinition {
   CancelNotification?: (
     request: CancelNotificationRequest,
   ) => CancelNotificationResponse | Promise<CancelNotificationResponse>;
+  /**
+   * @description This endpoint is used to validate inbound data and determine the type of data included in the inbound message
+   * @param request Data received from the provider via an inbound method, such as a webhook
+   */
+  ValidateInboundData?: (
+    request: ValidateInboundDataRequest,
+  ) => ValidateInboundDataResponse | Promise<ValidateInboundDataRequest>;
+  /**
+   * @description This endpoint is used to normalize inbound tracking data and determine the type of data
+   * @param request Tracking data received from the provider via an inbound method, such as a webhook
+   */
+  NormalizeTrackingData?: (
+    request: NormalizeTrackingDataRequest,
+  ) => NormalizeTrackingDataResponse | Promise<NormalizeTrackingDataResponse>;
 }

package/src/app/carrier-app.ts

@@ -1,12 +1,27 @@
 import { CarrierAppDefinition } from '.';
 import { ConnectRuntimeApp, Method, Route, BrandedImages } from './internal';
-
+import { ApiEndpoints } from './constants';
 import { resolve } from 'path';
 import { readFileSync, existsSync } from 'fs';
 
 import { Metadata } from './internal/metadata';
 import { CarrierSpecification } from './internal/carrier-specificaion';
 import { CarrierAppMetadataSchema } from './metadata';
+import {
+  RegisterResponseSchema,
+  CancelNotificationResponseSchema,
+  CancelPickupResponseSchema,
+  SchedulePickupResponseSchema,
+  TrackingResponseSchema,
+  GetRatesResponseSchema,
+  VoidLabelsResponseSchema,
+  CreateLabelResponseSchema,
+  CreateManifestResponseSchema,
+  CreateNotificationResponseSchema,
+  ValidateInboundDataResponseSchema,
+  NormalizeTrackingDataResponseSchema,
+} from '../responses';
+import { Schema } from 'joi';
 
 const handleRequest = (implementation?: Function): any => {
   if (implementation) {
@@ -16,66 +31,12 @@ const handleRequest = (implementation?: Function): any => {
   }
 };
 
-const registerRoutes = (routes: Route[], definition: CarrierAppDefinition) => {
-  routes.push({
-    method: Method.POST,
-    path: '/Register',
-    handler: handleRequest(definition.Register),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/CreateLabel',
-    handler: handleRequest(definition.CreateLabel),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/VoidLabels',
-    handler: handleRequest(definition.VoidLabels),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/GetRates',
-    handler: handleRequest(definition.GetRates),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/CreateManifest',
-    handler: handleRequest(definition.CreateManifest),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/SchedulePickup',
-    handler: handleRequest(definition.SchedulePickup),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/CancelPickup',
-    handler: handleRequest(definition.CancelPickup),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/Track',
-    handler: handleRequest(definition.Track),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/CreateNotification',
-    handler: handleRequest(definition.CreateNotification),
-  });
-  routes.push({
-    method: Method.POST,
-    path: '/CancelNotification',
-    handler: handleRequest(definition.CancelNotification),
-  });
-};
-
 export class CarrierApp implements ConnectRuntimeApp {
   routes: Route[] = [];
   data: Metadata;
   redoc?: string;
   validate: () => string[] | undefined;
   constructor(definition: CarrierAppDefinition) {
-    registerRoutes(this.routes, definition);
     this.validate = () => {
       const results = CarrierAppMetadataSchema.validate(definition.Metadata, {
         allowUnknown: true,
@@ -85,6 +46,97 @@ export class CarrierApp implements ConnectRuntimeApp {
         return results.error.details.map((detail) => `${detail.message}`);
       }
     };
+    new Array<[Method, ApiEndpoints, any, Schema]>(
+      [
+        Method.POST,
+        ApiEndpoints.CancelNotification,
+        definition.CancelNotification,
+        CancelNotificationResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.CancelPickup,
+        definition.CancelPickup,
+        CancelPickupResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.CreateLabel,
+        definition.CreateLabel,
+        CreateLabelResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.CreateManifest,
+        definition.CreateManifest,
+        CreateManifestResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.CreateNotification,
+        definition.CreateNotification,
+        CreateNotificationResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.GetRates,
+        definition.GetRates,
+        GetRatesResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.NormalizeTrackingData,
+        definition.NormalizeTrackingData,
+        NormalizeTrackingDataResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.Register,
+        definition.Register,
+        RegisterResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.SchedulePickup,
+        definition.SchedulePickup,
+        SchedulePickupResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.Track,
+        definition.Track,
+        TrackingResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.ValidateInboundData,
+        definition.ValidateInboundData,
+        ValidateInboundDataResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.VoidLabels,
+        definition.VoidLabels,
+        VoidLabelsResponseSchema,
+      ],
+    ).forEach(([method, path, implementation, schema]) => {
+      if (implementation) {
+        this.routes.push({
+          method,
+          path,
+          handler: handleRequest(implementation as Function),
+          validateResponse: (result: any): string[] | undefined => {
+            const validationResults = schema.validate(result, {
+              abortEarly: false,
+            });
+            const errors = validationResults?.error?.details?.map(
+              (detail) => detail.message,
+            );
+            return errors;
+          },
+        });
+      }
+    });
     this.data = new Metadata(definition);
 
     const jsonSpecPath = resolve(__dirname, '../../spec.json');

package/src/app/constants.ts

@@ -0,0 +1,14 @@
+export enum ApiEndpoints {
+  Register = '/Register',
+  CreateLabel = '/CreateLabel',
+  VoidLabels = '/VoidLabels',
+  GetRates = '/GetRates',
+  CreateManifest = '/CreateManifest',
+  SchedulePickup = '/SchedulePickup',
+  CancelPickup = '/CancelPickup',
+  Track = '/Track',
+  CreateNotification = '/CreateNotification',
+  CancelNotification = '/CancelNotification',
+  ValidateInboundData = '/ValidateInboundData',
+  NormalizeTrackingData = '/NormalizeTrackingData',
+}

package/src/app/internal/route.ts

@@ -10,4 +10,5 @@ export interface Route {
   path: string;
   method: Method;
   handler?: (req: any) => any | Promise<any>;
+  validateResponse?: (response: any) => string[] | undefined;
 }

package/src/models/authorization.ts

@@ -0,0 +1,4 @@
+export class Authorization {
+  access_token?: string;
+  connection_context?: any;
+}

package/src/models/billing/billing-categories.ts

@@ -1,3 +1,5 @@
+import Joi from 'joi';
+
 /** @description Category for a billing line item */
 export enum BillingCategories {
   Uncategorized = 'uncategorized',
@@ -23,3 +25,7 @@ export enum BillingCategories {
   /** @description Amount to be paid to the driver, used for local delivery and courier services. */
   Tip = 'tip',
 }
+
+export const BillingCategoriesSchema = Joi.string().valid(
+  ...Object.values(BillingCategories),
+);

package/src/models/billing/billing-line-item.ts

@@ -1,5 +1,9 @@
-import { BillingCategories } from './billing-categories';
-import { Currency } from '../currency';
+import {
+  BillingCategories,
+  BillingCategoriesSchema,
+} from './billing-categories';
+import { Currency, CurrencySchema } from '../currency';
+import Joi from 'joi';
 
 /** @description Basic structure of each charge or line item */
 export class BillingLineItem {
@@ -9,3 +13,11 @@ export class BillingLineItem {
   memo?: string;
   amount!: Currency;
 }
+
+export const BillingLineItemSchema = Joi.object({
+  billing_category: BillingCategoriesSchema.required(),
+  carrier_description: Joi.string().optional().empty(),
+  carrier_billing_code: Joi.string().optional().empty(),
+  memo: Joi.string().optional().empty(),
+  amount: CurrencySchema.required(),
+});

package/src/models/currency.ts

@@ -1,5 +1,12 @@
+import Joi from 'joi';
+
 /** @description Basic structure for defining an amount of money and its currency */
 export class Currency {
   currency!: string;
   amount!: string;
 }
+
+export const CurrencySchema = Joi.object({
+  currency: Joi.string().required(),
+  amount: Joi.string().required(),
+});

package/src/models/documents/document-type.ts

@@ -1,3 +1,5 @@
+import Joi from 'joi';
+
 /** @description Types of documents */
 export enum DocumentType {
   Label = 'label',
@@ -5,3 +7,7 @@ export enum DocumentType {
   CommercialInvoice = 'commercial_invoice',
   BillOfLading = 'bill_of_lading',
 }
+
+export const DocumentTypeSchema = Joi.string().valid(
+  ...Object.values(DocumentType),
+);

package/src/models/documents/document.ts

@@ -1,5 +1,9 @@
-import { DocumentType } from './document-type';
-import { DocumentFormat } from '../labels/document-formats';
+import { DocumentType, DocumentTypeSchema } from './document-type';
+import {
+  DocumentFormat,
+  DocumentFormatSchema,
+} from '../labels/document-formats';
+import Joi from 'joi';
 
 /** @description Basic structure for a document */
 export class Document {
@@ -7,3 +11,8 @@ export class Document {
   data!: string;
   format!: DocumentFormat;
 }
+export const DocumentSchema = Joi.object({
+  type: Joi.array().required().min(1).items(DocumentTypeSchema),
+  data: Joi.string().required(),
+  format: DocumentFormatSchema.required(),
+});

package/src/models/identifier.ts

@@ -1,5 +1,12 @@
+import Joi from 'joi';
+
 /** @description Key value pair to allow custom properties */
 export class Identifier {
   type!: string;
   value!: string;
 }
+
+export const IdentifierSchema = Joi.object({
+  type: Joi.string().required(),
+  value: Joi.string().required(),
+});

package/src/models/inbound-content-types.ts

@@ -0,0 +1,10 @@
+import Joi from 'joi';
+
+/** @description Types of inbound content */
+export enum InboundDataContentTypes {
+  /** @description Tracking information */
+  Tracking = 'tracking',
+}
+export const InboundDataContentTypesSchema = Joi.string().valid(
+  ...Object.values(InboundDataContentTypes),
+);

package/src/models/index.ts

@@ -1,4 +1,5 @@
 export * from './addresses';
+export * from './authorization';
 export * from './billing';
 export * from './customs';
 export * from './errors';
@@ -20,3 +21,4 @@ export * from './resource-download';
 export * from './taxes';
 export * from './documents';
 export * from './time-window';
+export * from './inbound-content-types';

package/src/models/labels/document-formats.ts

@@ -1,6 +1,11 @@
+import Joi from 'joi';
+
 /** @description Label data type */
 export enum DocumentFormat {
   Pdf = 'PDF',
   Zpl = 'ZPL',
   Png = 'PNG',
 }
+export const DocumentFormatSchema = Joi.string().valid(
+  ...Object.values(DocumentFormat),
+);

package/src/models/labels/form-download.ts

@@ -1,5 +1,10 @@
-import { ResourceDownload } from '../resource-download';
+import Joi from 'joi';
+import { ResourceDownload, ResourceDownloadSchema } from '../resource-download';
 
 export class FormDownload extends ResourceDownload {
   form_data?: string;
 }
+
+export const FormDownloadSchema = ResourceDownloadSchema.keys({
+  form_data: Joi.string().optional().empty(),
+});

package/src/models/labels/label-download.ts

@@ -1,5 +1,10 @@
-import { ResourceDownload } from '../resource-download';
+import Joi from 'joi';
+import { ResourceDownload, ResourceDownloadSchema } from '../resource-download';
 
 export class LabelDownload extends ResourceDownload {
   label_data?: string;
 }
+
+export const LabelDownloadSchema = ResourceDownloadSchema.keys({
+  label_data: Joi.string().optional().empty(),
+});

package/src/models/labels/label-package.ts

@@ -1,5 +1,6 @@
-import { Identifier } from '../identifier';
-import { Document } from '../documents';
+import { Identifier, IdentifierSchema } from '../identifier';
+import { Document, DocumentSchema } from '../documents';
+import Joi from 'joi';
 
 /** @description Package information provided by the carrier */
 export class LabelPackage {
@@ -8,3 +9,9 @@ export class LabelPackage {
   alternative_identifiers?: Identifier[];
   documents?: Document[];
 }
+
+export const LabelPackageSchema = Joi.object({
+  tracking_number: Joi.string().optional().empty(),
+  alternative_identifiers: Joi.array().optional().items(IdentifierSchema),
+  documents: Joi.array().optional().items(DocumentSchema),
+});

package/src/models/labels/void-response.ts

@@ -1,3 +1,5 @@
+import Joi from 'joi';
+import { BillingLineItem, BillingLineItemSchema } from '../billing';
 /** @description Basic structure for a response to void a label */
 export class VoidResponse {
   /** @description Id for the void response */
@@ -6,4 +8,13 @@ export class VoidResponse {
   message?: string;
   /** @description Any errors from attempting to void */
   errors?: string[];
+  /** @description Individual Billing Line items which remain after voiding the label, e.g. a cancellation fee. */
+  billing_line_items?: BillingLineItem[];
 }
+
+export const VoidResponseSchema = Joi.object({
+  void_request_id: Joi.string().required(),
+  message: Joi.string().optional().empty(),
+  errors: Joi.array().optional().items(Joi.string()),
+  billing_line_items: Joi.array().optional().items(BillingLineItemSchema),
+});

package/src/models/manifests/manifest.ts

@@ -1,4 +1,5 @@
-import { ResourceDownload } from '../resource-download';
+import Joi from 'joi';
+import { ResourceDownload, ResourceDownloadSchema } from '../resource-download';
 
 /** @description Basic structure of a manifest */
 export class Manifest {
@@ -7,3 +8,10 @@ export class Manifest {
   document_href?: string;
   document_data?: string;
 }
+
+export const ManifestSchema = Joi.object({
+  manifest_id: Joi.string().optional().empty(),
+  document_download: ResourceDownloadSchema.optional(),
+  document_href: Joi.string().optional().empty(),
+  document_data: Joi.string().optional().empty(),
+});

package/src/models/pickup/pickup-confirmation.ts

@@ -1,5 +1,9 @@
-import { Identifier } from '../identifier';
-import { ShipmentIdentifier } from './shipment-identifier';
+import Joi from 'joi';
+import { Identifier, IdentifierSchema } from '../identifier';
+import {
+  ShipmentIdentifier,
+  ShipmentIdentifierSchema,
+} from './shipment-identifier';
 
 /** @description Basic structure for a pickup confirmation */
 export class PickupConfirmation {
@@ -7,3 +11,8 @@ export class PickupConfirmation {
   alternate_identifiers?: Identifier[];
   shipment_identifiers?: ShipmentIdentifier[];
 }
+export const PickupConfirmationSchema = Joi.object({
+  confirmation_id: Joi.string().optional().empty(),
+  alternate_identifiers: Joi.array().optional().items(IdentifierSchema),
+  shipment_identifiers: Joi.array().optional().items(ShipmentIdentifierSchema),
+});

package/src/models/pickup/pickup-window.ts

@@ -1,3 +1,5 @@
+import Joi from 'joi';
+
 /** @description Time window for pickup */
 export class PickupWindow {
   time_zone_iana!: string;
@@ -5,3 +7,9 @@ export class PickupWindow {
   start_time?: string;
   end_time?: string;
 }
+export const PickupWindowSchema = Joi.object({
+  time_zone_iana: Joi.string().required(),
+  pickup_date: Joi.string().required().isoDate(),
+  start_time: Joi.string().optional().isoDate(),
+  end_time: Joi.string().optional().isoDate(),
+});

package/src/models/pickup/shipment-identifier.ts

@@ -1,7 +1,13 @@
-import { Identifier } from '../identifier';
+import Joi from 'joi';
+import { Identifier, IdentifierSchema } from '../identifier';
 
 /** @description Identifier object for shiments */
 export class ShipmentIdentifier {
   tracking_number?: string;
   alternate_identifiers?: Identifier[];
 }
+
+export const ShipmentIdentifierSchema = Joi.object({
+  tracking_number: Joi.string().optional().empty(),
+  alternate_identifiers: Joi.array().optional().items(IdentifierSchema),
+});

package/src/models/rates/rate.ts

@@ -1,5 +1,9 @@
-import { BillingLineItem } from '../billing/billing-line-item';
-import { TimeWindow } from '../time-window';
+import Joi from 'joi';
+import {
+  BillingLineItem,
+  BillingLineItemSchema,
+} from '../billing/billing-line-item';
+import { TimeWindow, TimeWindowSchema } from '../time-window';
 
 /** @description Basic structure for a rate */
 export class Rate {
@@ -28,3 +32,17 @@ export class Rate {
    */
   expiration_datetime?: string;
 }
+
+export const RateSchema = Joi.object({
+  service_code: Joi.string().optional().empty(),
+  ship_datetime: Joi.string().optional().empty().isoDate(),
+  estimated_delivery_datetime: Joi.string().optional().empty().isoDate(),
+  billing_line_items: Joi.array().optional().items(BillingLineItemSchema),
+  error_messages: Joi.array().optional().items(Joi.string()),
+  warning_messages: Joi.array().optional().items(Joi.string()),
+  negotiated_rate: Joi.boolean().optional(),
+  carrier_pickup_window: TimeWindowSchema.optional(),
+  delivery_window: TimeWindowSchema.optional(),
+  carrier_rate_id: Joi.string().optional().empty(),
+  expiration_datetime: Joi.string().optional().empty().isoDate(),
+});

package/src/models/registration/credentials.ts

@@ -1,5 +1,12 @@
+import Joi from 'joi';
+
 /** @description Basic structure for credentials */
 export class Credentials {
   username!: string;
   password!: string;
 }
+
+export const CredentialsSchema = Joi.object({
+  username: Joi.string().required(),
+  password: Joi.string().required(),
+});

package/src/models/resource-download.ts

@@ -1,5 +1,12 @@
+import Joi from 'joi';
+
 /** @description Basic structure for a resource to download */
 export class ResourceDownload {
   href?: string;
   data?: string;
 }
+
+export const ResourceDownloadSchema = Joi.object({
+  href: Joi.string().optional().empty(),
+  data: Joi.string().optional().empty(),
+});

package/src/models/time-window.ts

@@ -1,3 +1,5 @@
+import Joi from 'joi';
+
 /** @description Basic structure for defining a time window */
 export class TimeWindow {
   /** @description The local time zone represented in IANA. See https://www.iana.org/time-zones.
@@ -15,3 +17,9 @@ export class TimeWindow {
    */
   end_window?: string;
 }
+
+export const TimeWindowSchema = Joi.object({
+  time_zone_iana: Joi.string().required(),
+  start_window: Joi.string().required().isoDate(),
+  end_window: Joi.string().optional().empty().isoDate(),
+});

package/src/models/tracking/index.ts

@@ -5,3 +5,4 @@ export * from './track-event';
 export * from './tracking-attribute';
 export * from './tracking-identifier';
 export * from './tracking-info';
+export * from './update-method';