@shipengine/connect-carrier-api 2.4.6 → 2.5.0

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

@@ -13,6 +13,7 @@ import {
   ValidateInboundDataRequest,
   NormalizeTrackingDataRequest,
   GetRelayPointsRequest,
+  CreateLabelPaymentRequest,
 } from '../requests';
 
 import {
@@ -29,6 +30,7 @@ import {
   ValidateInboundDataResponse,
   NormalizeTrackingDataResponse,
   GetRelayPointsResponse,
+  CreateLabelPaymentResponse,
 } from '../responses';
 
 import { CarrierAppMetadata } from './metadata/carrier-app-metadata';
@@ -48,6 +50,13 @@ export interface CarrierAppDefinition {
    * @param request Data needed by the provider to create a label
    */
   CreateLabel?: (request: CreateLabelRequest) => CreateLabelResponse | Promise<CreateLabelResponse>;
+  /**
+   * @description This method is used to create a label
+   * @param request Data needed by the provider to create a label
+   */
+  CreateLabelPayment?: (
+    request: CreateLabelPaymentRequest,
+  ) => CreateLabelPaymentResponse | Promise<CreateLabelPaymentResponse>;
   /**
    * @description This method is used to void multiple labels
    * @param request Data needed by the provider to void multiple labels

package/src/app/carrier-app.ts

@@ -15,6 +15,7 @@ import {
   GetRatesResponseSchema,
   VoidLabelsResponseSchema,
   CreateLabelResponseSchema,
+  CreateLabelPaymentResponseSchema,
   CreateManifestResponseSchema,
   CreateNotificationResponseSchema,
   ValidateInboundDataResponseSchema,
@@ -25,8 +26,11 @@ import { Schema } from 'joi';
 
 const handleRequest = (implementation?: Function): any => {
   if (implementation) {
-    return (request: any) => {
-      return implementation(request.body);
+    return async (request: any) => {
+      const { transaction_id } = request.body;
+      const result = await implementation(request.body);
+      result.transaction_id = transaction_id;
+      return result;
     };
   }
 };
@@ -69,6 +73,12 @@ export class CarrierApp implements ConnectRuntimeApp {
       ],
       [Method.POST, ApiEndpoints.CancelPickup, definition.CancelPickup, CancelPickupResponseSchema],
       [Method.POST, ApiEndpoints.CreateLabel, definition.CreateLabel, CreateLabelResponseSchema],
+      [
+        Method.POST,
+        ApiEndpoints.CreateLabelPayment,
+        definition.CreateLabelPayment,
+        CreateLabelPaymentResponseSchema,
+      ],
       [
         Method.POST,
         ApiEndpoints.CreateManifest,

package/src/app/constants.ts

@@ -1,6 +1,7 @@
 export enum ApiEndpoints {
   Register = '/Register',
   CreateLabel = '/CreateLabel',
+  CreateLabelPayment = '/CreateLabelPayment',
   VoidLabels = '/VoidLabels',
   GetRates = '/GetRates',
   CreateManifest = '/CreateManifest',

package/src/app/internal/carrier-specification.ts

@@ -95,6 +95,7 @@ export class CarrierSpecification {
     AppId: string;
     DefaultRateCard: string;
   };
+  RequiresLabelPayment?: boolean;
 
   constructor(definition: Carrier) {
     this.Images = {
@@ -116,5 +117,6 @@ export class CarrierSpecification {
     this.CarrierUrl = definition.CarrierUrl;
     this.Description = definition.Description;
     this.NativeRating = definition.NativeRating;
+    this.RequiresLabelPayment = definition.RequiresLabelPayment;
   }
 }

package/src/app/internal/metadata.ts

@@ -22,6 +22,10 @@ const mapFunctions = (app: CarrierAppDefinition): FunctionSpecification[] => {
     fns.push(fn('CreateLabel'));
   }
 
+  if (app.CreateLabelPayment) {
+    fns.push(fn('CreateLabelPayment'));
+  }
+
   if (app.VoidLabels) {
     fns.push(fn('VoidLabels'));
   }

package/src/app/metadata/carrier.ts

@@ -39,6 +39,7 @@ export interface Carrier {
     /** @description Default rate card to use for rating */
     DefaultRateCard: string;
   };
+  RequiresLabelPayment?: boolean;
 }
 
 const fileExists = (value: string, helpers: any) => {
@@ -90,4 +91,5 @@ export const CarrierSchema = Joi.object({
       .pattern(new RegExp('^.*.(svg)$'))
       .message('Images.Logo must be a svg file.'),
   }).required(),
+  RequiresLabelPayment: Joi.boolean().optional(),
 });

package/src/models/labels/index.ts

@@ -4,6 +4,9 @@ export * from './label-download';
 export * from './document-formats';
 export * from './label-layouts';
 export * from './label-message';
+export * from './label-details';
+export * from './label-payment-result';
+export * from './label-request';
 export * from './return-label-details';
 export * from './void-request';
 export * from './void-response';

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

@@ -0,0 +1,55 @@
+import {
+  ConfirmationTypes,
+  Document,
+  DocumentFormat,
+  LabelRequest,
+  LabelLayouts,
+  AdvancedOptions,
+  InsuranceProviders,
+  Package,
+  ShipTo,
+  ShipFrom,
+  PudoLocation,
+  RelayPointDetails,
+  ShipFromDisplay,
+  ReturnLabelDetails,
+  FulfillmentPlanDetails,
+  TimeWindow,
+  Identifier,
+} from '..';
+
+/** @description Basic structure for a label */
+export class LabelDetails implements LabelRequest {
+  correlation_id!: string;
+  service_code?: string;
+  ship_datetime!: string;
+  confirmation?: ConfirmationTypes;
+  label_format?: DocumentFormat;
+  label_layout?: LabelLayouts;
+  /** @description Whether the request is for a test */
+  is_test_label?: boolean;
+  /** @description Any additional options a shipment may require, including custom options */
+  advanced_options?: AdvancedOptions;
+  insurance_provider?: InsuranceProviders;
+  /** @description Whether the shipment is a return */
+  is_return_label!: boolean;
+  packages!: Package[];
+  ship_to!: ShipTo;
+  ship_from!: ShipFrom;
+  pickup_location?: PudoLocation;
+  relay_points?: RelayPointDetails;
+  ship_from_display?: ShipFromDisplay;
+  /** @description Whether the shipment requires next day shipping */
+  next_day?: boolean;
+  /** @description Whether the shipment is international */
+  international?: boolean;
+  reference?: string;
+  return_details?: ReturnLabelDetails;
+  fulfillment_plan_details?: FulfillmentPlanDetails;
+  attachments?: Document[];
+  /** @description The carrier pickup window is the time designated when the carrier will pickup your package from the initial location */
+  carrier_pickup_window?: TimeWindow;
+  /** @description Unique identifier for the carrier rate */
+  carrier_rate_id?: string;
+  alternative_identifiers?: Identifier[];
+}

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

@@ -0,0 +1,17 @@
+import Joi from 'joi';
+import { Identifier, IdentifierSchema } from '../identifier';
+
+/** @description Basic structure for a label payment result */
+export class LabelPaymentResult {
+  correlation_id!: string;
+  alternative_identifiers!: Identifier[];
+  error_messages?: string[];
+  warning_messages?: string[];
+}
+
+export const LabelPaymentResultSchema = Joi.object({
+  correlation_id: Joi.string().required(),
+  alternative_identifiers: Joi.array().required().items(IdentifierSchema),
+  error_messages: Joi.array().optional().items(Joi.string()),
+  warning_messages: Joi.array().optional().items(Joi.string()),
+});

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

@@ -0,0 +1,53 @@
+import {
+  AdvancedOptions,
+  ConfirmationTypes,
+  FulfillmentPlanDetails,
+  InsuranceProviders,
+  DocumentFormat,
+  LabelLayouts,
+  Package,
+  ReturnLabelDetails,
+  ShipFrom,
+  PudoLocation,
+  ShipFromDisplay,
+  ShipTo,
+  Document,
+  TimeWindow,
+  RelayPointDetails,
+  Identifier,
+} from '..';
+
+/** @description Basic structure for a request to create a label */
+export interface LabelRequest {
+  service_code?: string;
+  ship_datetime: string;
+  confirmation?: ConfirmationTypes;
+  label_format?: DocumentFormat;
+  label_layout?: LabelLayouts;
+  /** @description Whether the request is for a test */
+  is_test_label?: boolean;
+  /** @description Any additional options a shipment may require, including custom options */
+  advanced_options?: AdvancedOptions;
+  insurance_provider?: InsuranceProviders;
+  /** @description Whether the shipment is a return */
+  is_return_label: boolean;
+  packages: Package[];
+  ship_to: ShipTo;
+  ship_from: ShipFrom;
+  pickup_location?: PudoLocation;
+  relay_points?: RelayPointDetails;
+  ship_from_display?: ShipFromDisplay;
+  /** @description Whether the shipment requires next day shipping */
+  next_day?: boolean;
+  /** @description Whether the shipment is international */
+  international?: boolean;
+  reference?: string;
+  return_details?: ReturnLabelDetails;
+  fulfillment_plan_details?: FulfillmentPlanDetails;
+  attachments?: Document[];
+  /** @description The carrier pickup window is the time designated when the carrier will pickup your package from the initial location */
+  carrier_pickup_window?: TimeWindow;
+  /** @description Unique identifier for the carrier rate */
+  carrier_rate_id?: string;
+  alternative_identifiers?: Identifier[];
+}

package/src/models/manifests/index.ts

@@ -1,2 +1,4 @@
 export * from './label';
 export * from './manifest';
+export * from './manifest-request-shipment';
+export * from './manifest-error';

package/src/models/manifests/manifest-error.ts

@@ -0,0 +1,11 @@
+import Joi from 'joi';
+
+export interface ManifestError {
+  manifest_request_shipment_ids: string[];
+  message: string;
+}
+
+export const ManifestErrorSchema = Joi.object({
+  manifest_request_shipment_ids: Joi.array().required(),
+  message: Joi.string().optional(),
+});

package/src/models/manifests/manifest-request-shipment.ts

@@ -0,0 +1,5 @@
+import { ShippedShipment } from '../pickup/shipped-shipment';
+
+export class ManifestRequestShipment extends ShippedShipment {
+  manifest_request_shipment_id!: string;
+}

package/src/models/manifests/manifest.ts

@@ -11,6 +11,7 @@ export class Manifest {
   document_href?: string;
   /** @deprecated This property is no longer used please use the document_download */
   document_data?: string;
+  manifest_request_shipment_ids?: string[];
 }
 
 export const ManifestSchema = Joi.object({
@@ -18,4 +19,5 @@ export const ManifestSchema = Joi.object({
   document_download: ResourceDownloadSchema.optional(),
   document_href: Joi.string().optional().empty(),
   document_data: Joi.string().optional().empty(),
+  manifest_request_shipment_ids: Joi.array().optional().items(Joi.string()),
 });

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

@@ -0,0 +1,7 @@
+import { BaseRequest } from './base-request';
+import { LabelDetails } from '../models';
+
+/** @description Basic structure for a request to create one or more label payments */
+export class CreateLabelPaymentRequest extends BaseRequest {
+  labels!: LabelDetails[];
+}

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

@@ -15,10 +15,12 @@ import {
   Document,
   TimeWindow,
   RelayPointDetails,
+  LabelRequest,
+  Identifier,
 } from '../models';
 
 /** @description Basic structure for a request to create a label */
-export class CreateLabelRequest extends BaseRequest {
+export class CreateLabelRequest extends BaseRequest implements LabelRequest {
   service_code?: string;
   ship_datetime!: string;
   confirmation?: ConfirmationTypes;
@@ -49,4 +51,5 @@ export class CreateLabelRequest extends BaseRequest {
   carrier_pickup_window?: TimeWindow;
   /** @description Unique identifier for the carrier rate */
   carrier_rate_id?: string;
+  alternative_identifiers?: Identifier[];
 }

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

@@ -1,11 +1,11 @@
 import { BaseRequest } from './base-request';
-import { ShipFrom, AdvancedOptions, ShippedShipment } from '../models';
+import { ShipFrom, AdvancedOptions, ManifestRequestShipment } from '../models';
 
 /** @description Basic structure for a request to create manifests */
 export class CreateManifestRequest extends BaseRequest {
   ship_from?: ShipFrom;
-  included_labels?: ShippedShipment[];
-  excluded_labels?: ShippedShipment[];
+  included_labels?: ManifestRequestShipment[];
+  excluded_labels?: ManifestRequestShipment[];
   open_datetime?: string;
   close_datetime!: string;
   advanced_options?: AdvancedOptions;

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

@@ -1,3 +1,4 @@
+import { ManifestRequestShipment } from '../models';
 import { BaseRequest } from './base-request';
 
 /** @description Basic structure for a request to get previousely created manifests */
@@ -10,4 +11,10 @@ export class GetManifestRequest extends BaseRequest {
 
   // Default false: Allow up to 5 checks to DHL before returning.
   return_immediately?: boolean;
+
+  // Labels included, identical to the labels send on the create manifest call
+  included_labels?: ManifestRequestShipment[];
+
+  // Labels excluded, identical to the labels send on the create manifest call
+  excluded_labels?: ManifestRequestShipment[];
 }

package/src/requests/index.ts

@@ -1,5 +1,6 @@
 export * from './cancel-pickup-request';
 export * from './create-label-request';
+export * from './create-label-payment-request';
 export * from './create-manifest-request';
 export * from './get-manifest-request';
 export * from './get-rates-request';

package/src/responses/create-label-payment-response.ts

@@ -0,0 +1,14 @@
+import Joi from 'joi';
+import { BaseResponse, BaseResponseSchema } from './base-response';
+import { LabelPaymentResult, LabelPaymentResultSchema } from '../models';
+
+/** @description Basic structure for a response to create a label */
+export class CreateLabelPaymentResponse extends BaseResponse {
+  transaction_id!: string;
+  results!: LabelPaymentResult[];
+}
+
+export const CreateLabelPaymentResponseSchema = BaseResponseSchema.keys({
+  transaction_id: Joi.string().required(),
+  results: Joi.array().required().items(LabelPaymentResultSchema),
+});

package/src/responses/create-manifest-response.ts

@@ -1,5 +1,5 @@
 import { BaseResponse, BaseResponseSchema } from './base-response';
-import { Manifest, ManifestSchema } from '../models';
+import { Manifest, ManifestSchema, ManifestError, ManifestErrorSchema } from '../models';
 import Joi from 'joi';
 import { ManifestStatus, ManifestStatusSchema } from '../models/manifest-status';
 
@@ -7,6 +7,7 @@ import { ManifestStatus, ManifestStatusSchema } from '../models/manifest-status'
 export class CreateManifestResponse extends BaseResponse {
   transaction_id!: string;
   manifests?: Manifest[];
+  errors?: ManifestError[];
   manifest_request_id?: number;
   manifest_status?: ManifestStatus;
   total_shipments?: number;
@@ -17,6 +18,7 @@ export class CreateManifestResponse extends BaseResponse {
 export const CreateManifestResponseSchema = BaseResponseSchema.keys({
   transaction_id: Joi.string().required(),
   manifests: Joi.array().optional().items(ManifestSchema),
+  errors: ManifestErrorSchema.optional(),
   manifest_request_id: Joi.number().optional(),
   manifest_status: ManifestStatusSchema.optional,
   total_shipments: Joi.number().optional(),

package/src/responses/index.ts

@@ -1,5 +1,6 @@
 export * from './cancel-pickup-response';
 export * from './create-label-response';
+export * from './create-label-payment-response';
 export * from './create-manifest-response';
 export * from './get-rates-response';
 export * from './register-response';