@shipengine/connect-carrier-api 2.10.0 → 2.11.0-beta

package/src/app/carrier-app.ts

@@ -5,7 +5,7 @@ import { OpenApiSpecification } from '../spec';
 
 import { Metadata } from './internal/metadata';
 import { CarrierSpecification } from './internal/carrier-specification';
-import { CarrierAppMetadataSchema } from './metadata';
+import { CarrierAppMetadata, CarrierAppMetadataSchema } from './metadata';
 import {
   RegisterResponseSchema,
   CancelNotificationResponseSchema,
@@ -26,6 +26,8 @@ import {
 import { Schema } from 'joi';
 import { DocumentTemplate } from './internal/document-template';
 import fs from 'fs';
+import { createGetRatesHandler } from './create-get-rates-handler';
+import { buildNativeRatingRoutes } from './build-native-rating-routes';
 
 const handleRequest = (implementation?: Function): any => {
   if (implementation) {
@@ -67,6 +69,9 @@ export class CarrierApp implements ConnectRuntimeApp {
         return results.error.details.map((detail) => `${detail.message}`);
       }
     };
+
+    const ratingImplementation = createGetRatesHandler(definition);
+
     new Array<[Method, ApiEndpoints, any, Schema]>(
       [
         Method.POST,
@@ -89,7 +94,7 @@ export class CarrierApp implements ConnectRuntimeApp {
         definition.CreateNotification,
         CreateNotificationResponseSchema,
       ],
-      [Method.POST, ApiEndpoints.GetRates, definition.GetRates, GetRatesResponseSchema],
+      [Method.POST, ApiEndpoints.GetRates, ratingImplementation, GetRatesResponseSchema],
       [
         Method.POST,
         ApiEndpoints.NormalizeTrackingData,
@@ -152,6 +157,9 @@ export class CarrierApp implements ConnectRuntimeApp {
         return await this.getDocumentTemplate(request);
       },
     });
+
+    buildNativeRatingRoutes(definition.Metadata).forEach((x) => this.routes.push(x));
+
     this.data = new Metadata(definition);
     this.redoc = JSON.stringify(OpenApiSpecification);
   }

package/src/app/create-get-rates-handler.ts

@@ -0,0 +1,119 @@
+import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { GetRatesRequest } from '../requests';
+import { CarrierAppDefinition } from './carrier-app-definition';
+import { Carrier } from './metadata/carrier';
+import { createContextBuilder } from './native-rating/base-rate-context';
+import createDynamicCarrier from './native-rating/create-dynamic-carrier';
+import { RateResultsAndId, RatingCarrier } from './native-rating/implementation-type';
+
+export const rateLogicName = 'rate-shipments.js';
+
+const runNativeRatingLocally = process.env.LOCAL_NATIVE_RATING
+  ? process.env.LOCAL_NATIVE_RATING !== 'false'
+  : process.env.NODE_ENV !== 'production';
+
+const createImplementation = (basePath: string): RatingCarrier | undefined => {
+  const logicPath = join(basePath, rateLogicName);
+
+  if (!existsSync(logicPath)) {
+    console.log(`Logic implementation does not exist at ${logicPath}`);
+    return undefined;
+  }
+
+  const rawImplementation = readFileSync(logicPath, 'utf8');
+  return createDynamicCarrier(rawImplementation);
+};
+
+const createNativeRatingHandler = (carrier: Carrier) => {
+  if (!carrier.NativeRating) {
+    console.log('Carrier does NOT have a Native Rating property in its config');
+    return undefined;
+  }
+  console.dir(carrier.NativeRating);
+  const basePath = carrier.NativeRating.Path;
+  if (!basePath) {
+    console.log('Carrier does NOT have a Native Rating path set');
+    return undefined;
+  }
+
+  if (!existsSync(basePath)) {
+    console.log(`Path for Native Rating '${basePath}' does not exist`);
+    return undefined;
+  }
+
+  try {
+    const buildContext = createContextBuilder(basePath);
+    const defaultImplementation = createImplementation(basePath);
+    const rateCards = Object.fromEntries(
+      carrier.NativeRating.RateCards?.map((card) => {
+        const impl = createImplementation(join(basePath, card.Id)) || defaultImplementation;
+        if (!impl) {
+          throw new Error(
+            `Cannot find default nor card specific rating logic for rate card ${card.Id}`,
+          );
+        }
+
+        const context = buildContext(card);
+        const rateShipments = (req: GetRatesRequest): Promise<RateResultsAndId[]> =>
+          impl.rateShipments(context, [{ id: 'rate-request', shipment: req }]);
+
+        return [card.Id, rateShipments];
+      }) || [],
+    );
+
+    const defaultRateCard = rateCards[carrier.NativeRating.DefaultRateCardId];
+    if (!defaultRateCard) {
+      throw new Error(
+        `Could not find a rate card definition for default rate card ${carrier.NativeRating.DefaultRateCardId}`,
+      );
+    }
+
+    return async (req: GetRatesRequest) => {
+      const rateCardId = req.metadata?.['native-rating-rate-card'];
+      const rateShipments = rateCardId ? rateCards[rateCardId] : defaultRateCard;
+
+      if (!rateShipments) {
+        throw new Error(`Could not find rate card ${rateCardId}`);
+      }
+
+      const results = await rateShipments(req);
+      return results.find((x) => x.id === 'rate-request');
+    };
+  } catch (err: any) {
+    console.warn(err?.message);
+    return undefined;
+  }
+};
+
+export const createGetRatesHandler = (definition: CarrierAppDefinition) => {
+  if (!runNativeRatingLocally) {
+    return definition.GetRates;
+  }
+
+  const nativeRatingCarriers = definition.Metadata.Carriers.map((x) => ({
+    apiCode: x.ApiCode || x.Name,
+    handler: createNativeRatingHandler(x) || definition.GetRates,
+  })).filter((x) => x.handler !== undefined);
+
+  // If there aren't any native rating implementations found, return whatever is defined in the definition
+  // This is what should happen in production because the Kong gateway should route any rate requests for NR
+  // carriers directly to the Native Rating service
+  if (nativeRatingCarriers.length === 0) {
+    console.log('No native rating implementations, returning GetRates implementation');
+    return definition.GetRates;
+  }
+
+  // If there's only a single carrier defined, just return the Native Rating handler so that we can avoid
+  // requiring the "carrier_code" property be set on the "metadata" object when testing
+  if (definition.Metadata.Carriers.length === 1) {
+    console.log('Only a single carrier and it uses Native Rating');
+    return nativeRatingCarriers[0].handler;
+  }
+
+  const implementationLookup = Object.fromEntries(
+    nativeRatingCarriers.map((x) => [x.apiCode, x.handler]),
+  );
+
+  return (req: GetRatesRequest) => implementationLookup[req.metadata?.['carrier_code']]?.(req);
+};

package/src/app/index.ts

@@ -1,3 +1,4 @@
 export * from './metadata';
 export * from './carrier-app-definition';
 export * from './carrier-app';
+export * from './native-rating';

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

@@ -17,6 +17,8 @@ import {
 import { LabelFormatsEnum } from '../metadata/label-formats';
 import { LabelSizesEnum } from '../metadata/label-sizes';
 import { CarrierAttributeEnum } from '../metadata/carrier-attributes';
+import { NativeRatingSpecification } from './native-rating-specification';
+import { NativeRatingConfiguration } from '../metadata/native-rating-configuration';
 
 export const mapShippingOptions = (
   options?: ShippingOptionDictionary,
@@ -71,6 +73,18 @@ const mapAccountModal = (modal: AccountModals): AccountModals => {
   };
 };
 
+const mapNativeRating = (
+  model?: NativeRatingConfiguration,
+): NativeRatingSpecification | undefined => {
+  if (!model) {
+    return undefined;
+  }
+
+  return {
+    DefaultRateCard: model.DefaultRateCardId,
+  };
+};
+
 /** @description This represents what we send to data manager */
 export class CarrierSpecification {
   Id: string;
@@ -92,10 +106,7 @@ export class CarrierSpecification {
     LogoUrl: string;
     IconUrl: string;
   };
-  NativeRating?: {
-    AppId: string;
-    DefaultRateCard: string;
-  };
+  NativeRating?: NativeRatingSpecification;
   DocumentTemplate?: string;
 
   constructor(definition: Carrier) {
@@ -118,7 +129,7 @@ export class CarrierSpecification {
     this.TrackingUrl = definition.TrackingUrl;
     this.CarrierUrl = definition.CarrierUrl;
     this.Description = definition.Description;
-    this.NativeRating = definition.NativeRating;
+    this.NativeRating = mapNativeRating(definition.NativeRating);
     this.DocumentTemplate = definition.DocumentTemplate;
   }
 }

package/src/app/internal/native-rating-specification.ts

@@ -0,0 +1,5 @@
+/** Specification for a Native Rating implementation */
+export interface NativeRatingSpecification {
+  /** External id of the default rate card */
+  DefaultRateCard: string;
+}

package/src/app/internal/route.ts

@@ -1,3 +1,5 @@
+import { Request } from 'express';
+
 export enum Method {
   POST = 'post',
   GET = 'get',
@@ -6,9 +8,24 @@ export enum Method {
   DELETE = 'delete',
 }
 
-export interface Route {
-  path: string;
-  method: Method;
+/** @description The definition for a route that will serve up the contents of a file */
+export interface FileRoute {
+  /** @description The file that should be sent to the client. If this is set, handler will not be used. */
+  file: string | ((req: Request) => string | Promise<string>);
+}
+
+/** @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>;
+  /** @description The optional method used to validate the response for this route. Used for warning purposes. */
   validateResponse?: (response: any) => string[] | undefined;
 }
+
+/** @description The definition for all types of routes */
+export type Route = {
+  /** @description The path to the endpoint you wish to expose @example "/CreateLabel", "/sales_orders_export" */
+  path: string;
+  /** @description The http verb used for this endpoint @example "GET", "POST" */
+  method: Method;
+} & (FileRoute | HandlerRoute);

package/src/app/metadata/carrier.ts

@@ -7,8 +7,9 @@ import { CarrierAttributeEnum, CarrierAttributeEnumSchema } from './carrier-attr
 import { LabelFormatsEnum, LabelFormatsEnumSchema } from './label-formats';
 import { LabelSizesEnum, LabelSizesEnumSchema } from './label-sizes';
 import { ConfirmationDictionary, ConfirmationDictionarySchema } from './confirmation-type';
-import { existsSync } from 'fs';
 import Joi from 'joi';
+import { NativeRatingConfiguration } from './native-rating-configuration';
+import { fileExists } from './custom-validators/file-exists';
 
 import { ApiCodeRegex, ApiCodeValidationMessage } from '@shipengine/connect-runtime';
 
@@ -52,24 +53,11 @@ export interface Carrier {
     Icon: string;
   };
   /** @description If this carrier uses Native Rating, details about the connection */
-  NativeRating?: {
-    /** @description Id of the Native Rating app */
-    AppId: string;
-
-    /** @description Default rate card to use for rating */
-    DefaultRateCard: string;
-  };
+  NativeRating?: NativeRatingConfiguration;
   /** @description This is the file path to the documents template, which is used by Rendering Service. Optional. If it's filled and template file provided, ApiCode must be filled. ApiCode will be used to identify the file in Rendering Service.*/
   DocumentTemplate?: string;
 }
 
-const fileExists = (value: string, helpers: any) => {
-  if (existsSync(value)) {
-    return value;
-  }
-  throw new Error("the file doesn't exist");
-};
-
 export const CarrierSchema = Joi.object({
   AccountModals: AccountModalsSchema.required(),
   PackageTypes: Joi.array().optional().items(PackageTypeSchema).unique('Id'),

package/src/app/metadata/custom-validators/file-exists.ts

@@ -0,0 +1,8 @@
+import { existsSync } from 'fs';
+
+export const fileExists = (value: string, helpers: any) => {
+  if (existsSync(value)) {
+    return value;
+  }
+  throw new Error("the file doesn't exist");
+};

package/src/app/metadata/native-rating-configuration.ts

@@ -0,0 +1,19 @@
+import Joi from 'joi';
+import { fileExists } from './custom-validators/file-exists';
+import { RateCard, RateCardSchema } from './rate-card';
+
+/** Configuration for attaching Native Rating to a carrier */
+export interface NativeRatingConfiguration {
+  /** @description Default rate card to use for rating */
+  DefaultRateCardId: string;
+  /** Path to rating logic and rate card data for this carrier */
+  Path?: string;
+  /** Array of rate cards for the carrier */
+  RateCards?: RateCard[];
+}
+
+export const NativeRatingConfigurationSchema = Joi.object({
+  DefaultRateCard: Joi.string().required(),
+  Path: Joi.string().optional().custom(fileExists, 'implementation path exists'),
+  RateCards: Joi.array().optional().items(RateCardSchema).unique('Id'),
+});

package/src/app/metadata/rate-card.ts

@@ -0,0 +1,14 @@
+import Joi from 'joi';
+
+/** Configuration for a given rate card */
+export interface RateCard {
+  /** Externally facing id of the rate card. */
+  Id: string;
+  /** Currency of the rate card. This uses the three-digit currency code format. */
+  Currency: string;
+}
+
+export const RateCardSchema = Joi.object({
+  Id: Joi.string().required(),
+  Currency: Joi.string().required().length(3),
+});

package/src/app/native-rating/base-rate-context.ts

@@ -0,0 +1,97 @@
+import { resolve } from 'path';
+import { readFileSync } from 'fs';
+import winston, { format, transports } from 'winston';
+import { NumericCurrency } from './numeric-currency';
+import { RatingContext } from './rating-context';
+import { RateCard } from '../metadata/rate-card';
+
+interface DataLookup {
+  rates: (keys: string[]) => Promise<{ [key: string]: NumericCurrency }>;
+  variables: (keys: string[]) => Promise<{ [key: string]: any }>;
+}
+
+type ZoneLookup = (keys: string[]) => Promise<{ [key: string]: any }>;
+
+/** Predicate that returns true if the value is defined, false if not */
+const valueIsUndefined = <T>([key, value]: [string, T | undefined]): boolean => {
+  const isIncluded = value !== undefined;
+
+  console.log(`${isIncluded ? '✔️' : '❌'} ${key}`);
+
+  return isIncluded;
+};
+
+/** Build a lookup function to find values for a list of keys */
+const buildLookup =
+  <TIn, TOut>(name: string, items: { key: string; value: TIn }[], mapper?: (item: TIn) => TOut) =>
+  (keys: string[]): Promise<{ [dataKey: string]: TOut }> => {
+    console.log(`Getting ${name} keys (${keys.length} total):`);
+    console.group();
+    try {
+      const things = keys.map((key) => {
+        const foundValue = items.find((item) => key === item.key)?.value;
+        const mappedValue = foundValue && mapper ? mapper(foundValue) : foundValue;
+        return [key, mappedValue] as [string, TOut | undefined];
+      });
+
+      const values = Object.fromEntries(things.filter(valueIsUndefined)) as {
+        [key: string]: TOut;
+      };
+      return Promise.resolve(values);
+    } finally {
+      console.groupEnd();
+    }
+  };
+
+const loadData = (basePath: string) => (dataType: string) => {
+  try {
+    const data = readFileSync(resolve(basePath, `${dataType}.json`));
+    const json = JSON.parse(data.toString());
+    return [dataType, json?.[dataType] || []];
+  } catch (err) {
+    return [dataType, []];
+  }
+};
+
+export const createContextBuilder = (basePath: string) => {
+  let zoneLookup: ZoneLookup;
+  const getZoneLookup = () => {
+    if (!zoneLookup) {
+      const zones = loadData(basePath)('zones')[1];
+      zoneLookup = buildLookup('zone', zones);
+    }
+    return zoneLookup;
+  };
+
+  const log = winston.createLogger({
+    format: format.combine(format.colorize(), format.timestamp(), format.metadata()),
+    transports: [new transports.Console({ level: 'debug' })],
+  });
+
+  return (rateCard: RateCard): RatingContext => {
+    let dataLookup: DataLookup;
+    const getDataLookup = () => {
+      if (!dataLookup) {
+        const loadedData = Object.fromEntries(
+          ['rates', 'variables'].map(loadData(resolve(basePath, rateCard.Id))),
+        );
+
+        dataLookup = {
+          rates: buildLookup('rate', loadedData.rates, (x: any) => ({
+            amount: +x,
+            currency: rateCard.Currency,
+          })),
+          variables: buildLookup('variables', loadedData.variables),
+        };
+      }
+      return dataLookup;
+    };
+
+    return {
+      getRates: (keys: string[]) => getDataLookup().rates(keys),
+      getVariables: (keys: string[]) => getDataLookup().variables(keys),
+      getZone: (keys: string[]) => getZoneLookup()(keys),
+      log,
+    };
+  };
+};

package/src/app/native-rating/context-results.ts

@@ -0,0 +1,3 @@
+export interface ContextResults<T> {
+  [dataKey: string]: T;
+}

package/src/app/native-rating/create-dynamic-carrier.ts

@@ -0,0 +1,82 @@
+import { VM, VMScript } from 'vm2';
+import { RateResultsAndId, RatingCarrier, ShipmentAndId } from './implementation-type';
+import { RatingContext } from './rating-context';
+
+/** Results of the carrier code validation **/
+interface CodeValidationResults {
+  errors?: string[];
+  /** Does the carrier code contain the get zones function */
+  hasGetZonesFunction: boolean;
+}
+
+/** Ensure that the carrier module has the correct shape
+ * @param module Object into which code should be exported
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const validateCode = (module?: any): CodeValidationResults => {
+  if (module?.exports?.default === undefined) {
+    return {
+      errors: ['Code must have a default export'],
+      hasGetZonesFunction: false,
+    };
+  }
+
+  const errors = [];
+  const { rateShipments, getZones } = module.exports.default;
+  const hasGetZonesFunction = getZones !== undefined;
+
+  if (typeof rateShipments !== 'function') {
+    errors.push("Code must contain a function named 'rateShipments'");
+  } else if (rateShipments.length !== 2) {
+    errors.push("'rateShipments' function must have two parameters");
+  }
+
+  return {
+    errors,
+    hasGetZonesFunction,
+  };
+};
+
+/** Create a dynamic carrier
+ * @param code Code that should be used for the carrier
+ * @returns Carrier with code ready to be executed
+ */
+const createDynamicCarrier = (code: string): RatingCarrier => {
+  // This is to make sure that the code we need to run doesn't get excluded because of dangling comments, etc.
+  const resetCode = code + ';\n /* */ \n';
+
+  const validationResults = new VM({
+    sandbox: { module: {}, validateCode },
+  }).run(`${resetCode}; validateCode(module);`);
+  if (validationResults.errors?.length > 0) {
+    throw new Error(validationResults.errors.join('; '));
+  }
+
+  const rateShipmentsScript = new VMScript(
+    `${resetCode} module.exports.default.rateShipments(context, shipment);`,
+  );
+
+  const executionVM = new VM({
+    sandbox: {
+      module: {},
+      context: {},
+      shipment: {},
+      zoneContext: {},
+      origin: {},
+      destination: {},
+    },
+  });
+
+  const carrier: RatingCarrier = {
+    rateShipments: (
+      context: RatingContext,
+      shipment: ShipmentAndId[],
+    ): Promise<RateResultsAndId[]> => {
+      return executionVM.setGlobals({ context, shipment }).run(rateShipmentsScript);
+    },
+  };
+
+  return carrier;
+};
+
+export default createDynamicCarrier;

package/src/app/native-rating/get-rates.ts

@@ -0,0 +1,9 @@
+import { ContextResults } from './context-results';
+import { NumericCurrency } from './numeric-currency';
+
+export type GetRatesResults = ContextResults<NumericCurrency>;
+
+/** Function to get rates from the context */
+export interface GetRates {
+  (dataKeys: string[]): Promise<GetRatesResults>;
+}

package/src/app/native-rating/get-variables.ts

@@ -0,0 +1,9 @@
+import { ContextResults } from './context-results';
+
+export type GetVariableResults = ContextResults<any>;
+
+/** Function to get rating variables from the context */
+export interface GetVariables {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (dataKeys: string[]): Promise<GetVariableResults>;
+}

package/src/app/native-rating/get-zone.ts

@@ -0,0 +1,9 @@
+import { ContextResults } from './context-results';
+
+export type GetZoneResults = ContextResults<any>;
+
+/** Function to get zone data from the context */
+export interface GetZone {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (dataKeys: string[]): Promise<GetZoneResults>;
+}

package/src/app/native-rating/implementation-type.ts

@@ -0,0 +1,34 @@
+import { Rate } from '../../models/rates';
+import { GetRatesRequest } from '../../requests/get-rates-request';
+import { RatingContext } from './rating-context';
+
+/** A rate request shipment with its corresponding id */
+export interface ShipmentAndId {
+  /** rate_request_identifier for the rate request */
+  id: string;
+  /** Shipment for the rate request */
+  shipment: GetRatesRequest;
+}
+
+/** Rate results with its corresponding rate request id */
+export interface RateResultsAndId {
+  /** rate_request_identifier for the corresponding rate request */
+  id: string;
+  /** Error, if any */
+  error?: unknown;
+  /** Rates for a given rate request */
+  rates: Rate[];
+}
+
+/** Implementation of a carrier */
+export interface RatingCarrier {
+  /** Rate shipments
+   * @param context Native Rating context that can be used by the implementation to interact with the underlying service
+   * @param shipment Shipments that should be rated
+   * @returns List of rates for the given shipments
+   */
+  rateShipments: (context: RatingContext, shipment: ShipmentAndId[]) => Promise<RateResultsAndId[]>;
+}
+
+/** Signify a validation error from the carrier */
+export class CarrierValidationError extends Error {}

package/src/app/native-rating/index.ts

@@ -0,0 +1,2 @@
+export * from './rating-context';
+export * from './implementation-type';

package/src/app/native-rating/numeric-currency.ts

@@ -0,0 +1,5 @@
+/** NumericCurrency so that we don't have to convert from the string Currency all over the place */
+export interface NumericCurrency {
+  currency: string;
+  amount: number | undefined;
+}

package/src/app/native-rating/rating-context.ts

@@ -0,0 +1,19 @@
+import { Logger } from 'winston';
+import { GetVariables } from './get-variables';
+import { GetRates } from './get-rates';
+import { GetZone } from './get-zone';
+
+/** Rates request context */
+export interface RatingContext {
+  /** Function to get rates for given keys */
+  getRates: GetRates;
+
+  /** Function to get variables for given keys */
+  getVariables: GetVariables;
+
+  /** Function to get zone for given keys */
+  getZone: GetZone;
+
+  /** Logger that implementers can use */
+  log: Logger;
+}

package/src/models/rates/rate.ts

@@ -26,8 +26,10 @@ export class Rate {
   carrier_rate_id?: string;
   /** @description DateTime after which the rate will no longer be accepted. ISO 8601 format, with local offset. Example: 2021-08-20T14:38:36.859237-05:00 */
   expiration_datetime?: string;
-  /** @description Estimated delivery text. It could be any text, a number, a date, etc. */
-  estimated_delivery_text?: string;
+  /** @description The Package type of this rate */
+  package_type?: string;
+  /** @description The zone this rate is for */
+  zone?: string;
 }
 
 export const RateSchema = Joi.object({
@@ -42,5 +44,6 @@ export const RateSchema = Joi.object({
   delivery_window: TimeWindowSchema.optional(),
   carrier_rate_id: Joi.string().optional().empty(),
   expiration_datetime: Joi.string().optional().empty().isoDate(),
-  estimated_delivery_text: Joi.string().optional().empty(),
+  package_type: Joi.string().optional().empty(),
+  zone: Joi.string().optional().empty(),
 });

package/src/models/shipment-item.ts

@@ -0,0 +1,7 @@
+/** And item that is part of a shipment */
+export interface ShipmentItem {
+  /** Sku of the item */
+  sku?: string;
+  /** Quantity of the item */
+  quantity?: number;
+}

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

@@ -11,6 +11,7 @@ import {
   FulfillmentPlanDetails,
   TimeWindow,
 } from '../models';
+import { ShipmentItem } from '../models/shipment-item';
 
 /** @description Basic structure for a request to get rates */
 export class GetRatesRequest extends BaseRequest {
@@ -30,4 +31,6 @@ export class GetRatesRequest extends BaseRequest {
   fulfillment_plan_details?: FulfillmentPlanDetails;
   /** @description The carrier pickup window is the time designated when the carrier will pickup your package from the initial location */
   carrier_pickup_window?: TimeWindow;
+  /** Items included in the shipment */
+  items?: ShipmentItem[];
 }