@shipengine/connect-carrier-api 2.4.7 → 2.5.1

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/manifest-request-shipment.ts

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

package/src/models/time-window.ts

@@ -5,7 +5,7 @@ export class TimeWindow {
   /** @description The local time zone represented in IANA. See https://www.iana.org/time-zones.
    * Example: America/Chicago
    */
-  time_zone_iana!: string;
+  time_zone_iana?: string;
   /** @description The start of the window when the pickup could be made relative to the time_zone_iana.
    * ISO 8601 format, with local offset
    * Example: 2021-08-20T14:38:36.859237-05:00
@@ -19,7 +19,7 @@ export class TimeWindow {
 }
 
 export const TimeWindowSchema = Joi.object({
-  time_zone_iana: Joi.string().required(),
-  start_window: Joi.string().required().isoDate(),
-  end_window: Joi.string().optional().empty().isoDate(),
+  time_zone_iana: Joi.string().optional().allow(null).empty(''),
+  start_window: Joi.string().optional().allow(null).empty('').isoDate(),
+  end_window: Joi.string().optional().allow(null).empty('').isoDate(),
 });

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/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/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';