@shipengine/connect-carrier-api 4.33.0 → 4.34.1-alpha-gold-28569.0

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

@@ -2,6 +2,7 @@ import { ImportedTrackingEvent } from '../models';
 import type { Request } from 'express';
 import {
   RegisterRequest,
+  BulkTrackingRequest,
   CreateLabelRequest,
   VoidLabelsRequest,
   CreateManifestRequest,
@@ -26,6 +27,7 @@ import {
 
 import {
   RegisterResponse,
+  BulkTrackingResponse,
   CreateLabelResponse,
   VoidLabelsResponse,
   CreateManifestResponse,
@@ -108,6 +110,13 @@ export interface CarrierAppDefinition {
    * @param request Data needed by the provider to track a shipment
    */
   Track?: (request: TrackingRequest) => TrackingResponse | Promise<TrackingResponse>;
+  /**
+   * @description This endpoint is used to get tracking information about multiple shipments in a single call
+   * @param request Data needed by the provider to track multiple shipments
+   */
+  BulkTrack?: (
+    request: BulkTrackingRequest,
+  ) => BulkTrackingResponse | Promise<BulkTrackingResponse>;
   /**
    * @description This endpoint is used to submit notification of the creation of a shipment
    * @param request Data needed by the provider to inform them of a shipment

package/src/app/constants.ts

@@ -8,6 +8,7 @@ export enum ApiEndpoints {
   SchedulePickup = '/SchedulePickup',
   CancelPickup = '/CancelPickup',
   Track = '/Track',
+  BulkTrack = '/BulkTrack',
   CreateNotification = '/CreateNotification',
   CancelNotification = '/CancelNotification',
   ValidateInboundData = '/ValidateInboundData',

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

@@ -7,6 +7,7 @@ export const createEndpointMapping = (
 ): [Method, string, Handler | 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.BulkTrack, definition.BulkTrack],
   [Method.POST, ApiEndpoints.CancelNotification, definition.CancelNotification],
   [Method.POST, ApiEndpoints.CancelPickup, definition.CancelPickup],
   [Method.POST, ApiEndpoints.CreateLabel, definition.CreateLabel],

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

@@ -7,4 +7,6 @@ export enum BillToParty {
   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',
+  /** @description The shipping charges are to be collected from the recipient upon delivery. */
+  Collect = 'collect',
 }

package/src/models/tracking/bulk-tracking-error.ts

@@ -0,0 +1,7 @@
+/** @description Error detail for a single item within a bulk tracking response */
+export class BulkTrackingError {
+  /** @description A code identifying the type of error encountered while tracking this item */
+  code!: string;
+  /** @description A human readable description of the error */
+  message!: string;
+}

package/src/models/tracking/index.ts

@@ -1,3 +1,4 @@
+export * from './bulk-tracking-error';
 export * from './imported-tracking-event-schema';
 export * from './imported-tracking-event';
 export * from './lat-long-schema';

package/src/requests/bulk-tracking-request.ts

@@ -0,0 +1,16 @@
+import { BaseRequest } from './base-request';
+import { TrackingIdentifier, TrackingAttribute } from '../models';
+
+/** @description A single shipment to request tracking information for as part of a bulk tracking request */
+export class BulkTrackingItem {
+  /** @description List of identifiers */
+  identifiers?: TrackingIdentifier[];
+  /** @description List of attributes */
+  attributes?: TrackingAttribute[];
+}
+
+/** @description Basic structure for a request to get tracking information for multiple shipments in a single call */
+export class BulkTrackingRequest extends BaseRequest {
+  /** @description The shipments to retrieve tracking information for */
+  items!: BulkTrackingItem[];
+}

package/src/requests/index.ts

@@ -1,3 +1,4 @@
+export * from './bulk-tracking-request';
 export * from './cancel-notification-request';
 export * from './cancel-pickup-request';
 export * from './create-label-request';

package/src/responses/bulk-tracking-response.ts

@@ -0,0 +1,20 @@
+import { BaseResponse } from './base-response';
+import { TrackingInfo } from '../models';
+import { BulkTrackingError } from '../models/tracking/bulk-tracking-error';
+
+/** @description Tracking result for a single item within a bulk tracking response */
+export class BulkTrackingResultItem {
+  /** @description The carrier specific tracking identifier for this shipment */
+  tracking_number!: string;
+  /** @description Tracking information for this shipment, present when tracking succeeded */
+  tracking_info?: TrackingInfo;
+  /** @description Error detail for this shipment, present when tracking failed */
+  error?: BulkTrackingError;
+}
+
+/** @description Basic structure for a response to get tracking information for multiple shipments in a single call */
+export class BulkTrackingResponse extends BaseResponse {
+  transaction_id!: string;
+  /** @description Per-item tracking results, in no guaranteed order relative to the request's items */
+  results!: BulkTrackingResultItem[];
+}

package/src/responses/index.ts

@@ -1,3 +1,4 @@
+export * from './bulk-tracking-response';
 export * from './cancel-notification-response-schema';
 export * from './cancel-notification-response';
 export * from './cancel-pickup-response-schema';