@shipengine/connect-carrier-api 2.1.21 → 2.2.0

package/src/app/internal/{carrier-app-specificaion.ts → carrier-app-specification.ts}

@@ -1,5 +1,6 @@
+import { AuthSpecification } from '../metadata/auth-specification';
 import { ShippingProviderConnector } from '../metadata/shipping-provider-connector';
-import { CarrierSpecification } from './carrier-specificaion';
+import { CarrierSpecification } from './carrier-specification';
 
 /** @description This represents a single integration which may contain multiple carrier sources */
 export interface CarrierAppSpecification {
@@ -9,6 +10,8 @@ export interface CarrierAppSpecification {
   Name: string;
   /** @description Information about the connector */
   Connector: ShippingProviderConnector;
+  /** @description The specification for authorizing with this carrier */
+  AuthProcess?: AuthSpecification;
   /** @description A list of carrier sources associated with this integration */
   Carriers: CarrierSpecification[];
 }

package/src/app/internal/metadata.ts

@@ -2,8 +2,9 @@ import { CarrierAppDefinition } from '../carrier-app-definition';
 import { ShippingProviderConnector } from '../metadata/shipping-provider-connector';
 import { FunctionSpecification } from '../metadata/function';
 
-import { CarrierAppSpecification } from './carrier-app-specificaion';
-import { CarrierSpecification } from './carrier-specificaion';
+import { CarrierAppSpecification } from './carrier-app-specification';
+import { CarrierSpecification } from './carrier-specification';
+import { AuthSpecification } from '../metadata/auth-specification';
 
 const fn = (name: string): FunctionSpecification => ({
   Name: name,
@@ -52,11 +53,16 @@ export class Metadata implements CarrierAppSpecification {
   Id: string;
   Name: string;
   Connector: ShippingProviderConnector;
+  AuthProcess?: AuthSpecification;
   Carriers: CarrierSpecification[];
 
   constructor(app: CarrierAppDefinition) {
     this.Id = app.Metadata.Id;
     this.Name = app.Metadata.Name;
+    this.AuthProcess = app.Metadata.AuthProcess;
+    if (this.AuthProcess) {
+      this.AuthProcess.Identifier.Version = '2.0';
+    }
     this.Carriers = app.Metadata.Carriers.map(
       (c) => new CarrierSpecification(c),
     );

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/app/metadata/auth-identifier.ts

@@ -0,0 +1,17 @@
+import Joi from 'joi';
+
+export enum AuthenticationType {
+  OAuth = 'oauth',
+}
+
+export class AuthIdentifier {
+  AuthenticationType!: AuthenticationType;
+  Version?: string;
+  IsSandbox?: boolean;
+}
+
+export const AuthIdentifierSchema = Joi.object({
+  AuthenticationType: Joi.string().required().valid('oauth'),
+  Version: Joi.string().optional(),
+  IsSandbox: Joi.bool().optional(),
+});

package/src/app/metadata/auth-specification.ts

@@ -0,0 +1,39 @@
+import { AuthIdentifier, AuthIdentifierSchema } from './auth-identifier';
+import {
+  AccessToken,
+  AccessTokenSchema,
+  AuthorizationConfiguration,
+  AuthorizationConfigurationSchema,
+  Parameter,
+  ParameterSchema,
+  RefreshTokenConfiguration,
+  RefreshTokenConfigurationSchema,
+  RequestTokenConfiguration,
+  RequestTokenConfigurationSchema,
+} from './monoauth';
+import Joi from 'joi';
+
+/** @description Used to specify information about an integrations authentication */
+export class AuthSpecification {
+  /** @description Identify the type of Auth being used by the integration */
+  Identifier!: AuthIdentifier;
+  /** @description Added to allow oauth 1.0 to work. */
+  access_token?: AccessToken;
+  /** @description Authorization: the beginning of an OAuth2.0 flow that ensures the user is logged in and approves access to the Resource. */
+  authorization?: AuthorizationConfiguration;
+  /** @description Request Token: server-server code for token exchange */
+  request_token?: RequestTokenConfiguration;
+  /** @description Refresh Token: server-server refresh token exchange for access token **NOTE: sometimes a new RT is also created** */
+  refresh_token?: RefreshTokenConfiguration;
+  /** @description Advanced configurations used for oauth 1.0 */
+  advanced_configuration?: Parameter[];
+}
+
+export const AuthSpecificationSchema = Joi.object({
+  Identifier: AuthIdentifierSchema,
+  access_token: AccessTokenSchema.optional(),
+  authorization: AuthorizationConfigurationSchema.optional(),
+  request_token: RequestTokenConfigurationSchema.optional(),
+  refresh_token: RefreshTokenConfigurationSchema.optional(),
+  advanced_configuration: Joi.array().optional().items(ParameterSchema),
+});

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

@@ -1,11 +1,18 @@
 import Joi from 'joi';
-import { Carrier, CarrierSchema } from './carrier';
+import {
+  AuthSpecification,
+  AuthSpecificationSchema,
+  Carrier,
+  CarrierSchema,
+} from '.';
 
 export interface CarrierAppMetadata {
   /** @description Id of the carrier app */
   Id: string;
   /** @description Name of the carrier */
   Name: string;
+  /** @description The specification for authorizing with this order source */
+  AuthProcess?: AuthSpecification;
   /** @description List of carriers for the app */
   Carriers: Carrier[];
 }
@@ -15,6 +22,7 @@ export const CarrierAppMetadataSchema = Joi.object({
     .uuid({ version: ['uuidv4'] })
     .required(),
   Name: Joi.string().required(),
+  AuthProcess: AuthSpecificationSchema.optional(),
   Carriers: Joi.array()
     .unique('Id')
     .required()

package/src/app/metadata/index.ts

@@ -1,7 +1,9 @@
 export * from './account-modals';
+export * from './auth-identifier';
+export * from './auth-specification';
+export * from './carrier';
 export * from './carrier-app-metadata';
 export * from './carrier-attributes';
-export * from './carrier';
 export * from './confirmation-type';
 export * from './country-association';
 export * from './diagnostic-routes';
@@ -9,6 +11,7 @@ export * from './enums';
 export * from './function';
 export * from './label-formats';
 export * from './label-sizes';
+export * from './monoauth';
 export * from './package-type';
 export * from './service-class';
 export * from './service-grade';

package/src/app/metadata/monoauth.ts

@@ -0,0 +1,171 @@
+import Joi from 'joi';
+
+export class Parameter {
+  /** @description The name of the parameter */
+  name!: string;
+  /** @description The value associated with the parameter */
+  value!: string;
+}
+
+export const MethodSchema = Joi.string().valid(
+  'GET',
+  'POST',
+  'DELETE',
+  'PUT',
+  'get',
+  'post',
+  'delete',
+  'put',
+);
+
+export const ParameterSchema = Joi.object({
+  name: Joi.string().required(),
+  value: Joi.string().required(),
+});
+
+export class DateTimeConfiguration {
+  /** @description JSONPath to the JSON element containing the date-time */
+  path!: string;
+  /** @description DateTime format string compliant with
+   * https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings */
+  date_time_format!: string;
+}
+
+export const DateTimeConfigurationSchema = Joi.object({
+  path: Joi.string().required(),
+  date_time_format: Joi.string().required(),
+});
+
+export type MapOfStrings = {
+  [key: string]: string;
+};
+
+/** @description Optional configuration to take full control of parsing and extracting fields
+ * from the integration's JSON response body.
+ * Note for JSONPath: strings not starting with $ are interpreted as string literals
+ */
+export class ResponseTransformationConfiguration {
+  /** @description JSONPath to the JSON element for access_token. */
+  access_token!: string;
+  /** @description JSONPath to the JSON element for token_type */
+  token_type!: string;
+  /** @description JSONPath to the JSON element for refresh_token */
+  refresh_token?: string;
+  /** @description JSONPath to the JSON element for expires_in. Mutually exclusive with expires_at */
+  expires_in?: string;
+  /** @description Configuration for parsing a date-time, when the integration is lacking expires_in.
+   * Mutually exclusive with expires_in.
+   */
+  expires_at?: DateTimeConfiguration;
+  /** @description Optional collection of properties to include in the connection_context sent back with the auth flow result.
+   *  Property value may be JSONPath or a string literal.
+   *  E.g.
+   *  "connection_context": {
+   *    "account_number": "$.data.account_number"
+   *  }
+   */
+  connection_context?: MapOfStrings;
+}
+
+export const MapOfStringsSchema = Joi.object().pattern(
+  Joi.string(),
+  Joi.string(),
+);
+
+export const ResponseTransformationConfigurationSchema = Joi.object({
+  access_token: Joi.string().required(),
+  token_type: Joi.string().required(),
+  refresh_token: Joi.string().optional(),
+  expires_in: Joi.string().optional(),
+  expires_at: DateTimeConfigurationSchema.optional(),
+  connection_context: MapOfStringsSchema.optional(),
+});
+
+export class AccessToken {
+  /** @description OAuth1 only. The url to obtain the temporary Access (aka Request) Token to start a flow **/
+  url_template!: string;
+}
+
+export const AccessTokenSchema = Joi.object({
+  url_template: Joi.string().required(),
+});
+
+export class RequestTokenConfiguration {
+  /** @description The url to obtain the access token using the authorization code on the backend @example "http://{auth_state:store_name}.store.com/admin/oauth/request", "http://store.com/oauth/request" */
+  url_template!: string;
+  /** @description A list of query parameters that will be attached to the url */
+  query_parameters?: Parameter[];
+  /** @description Method to use when making the server-server code for token request @example "GET", "POST" */
+  method?: string;
+  /** @description List of parameters that are sent to the integration when exchanging the code for the token. These are built using ContentType */
+  body?: Parameter[];
+  /** @description List of headers that are sent to the integration when requesting a token */
+  headers?: Parameter[];
+  /** @description Response payload parsing */
+  response?: ResponseTransformationConfiguration;
+}
+
+export const RequestTokenConfigurationSchema = Joi.object({
+  url_template: Joi.string().required(),
+  query_parameters: Joi.array().optional().items(ParameterSchema),
+  method: MethodSchema.optional(),
+  body: Joi.array().optional().items(ParameterSchema),
+  headers: Joi.array().optional().items(ParameterSchema),
+  response: ResponseTransformationConfigurationSchema.optional(),
+});
+
+export class RefreshTokenConfiguration {
+  /** @description The url to refresh the access token using the authorization code on the backend @example "http://{auth_state:store_name}.store.com/admin/oauth/refresh", "http://store.com/oauth/refresh" */
+  url_template!: string;
+  /** @description A list of query parameters that will be attached to the url */
+  query_parameters?: Parameter[];
+  /** @description Method to use when making the server-server code for token request @example "GET", "POST" */
+  method?: string;
+  /** @description List of parameters that are sent to the integration during the server-server refresh token request. These are built using the content type specified in the headers array. */
+  body?: Parameter[];
+  /** @description List of headers that are sent to the integration when refreshing a token */
+  headers?: Parameter[];
+  /** @description Response payload parsing */
+  response?: ResponseTransformationConfiguration;
+}
+
+export const RefreshTokenConfigurationSchema = Joi.object({
+  url_template: Joi.string().required(),
+  query_parameters: Joi.array().optional().items(ParameterSchema),
+  method: MethodSchema.optional(),
+  body: Joi.array().optional().items(ParameterSchema),
+  headers: Joi.array().optional().items(ParameterSchema),
+  response: ResponseTransformationConfigurationSchema.optional(),
+});
+
+export class NonceConfiguration {
+  name!: string;
+}
+
+export const NonceConfigurationSchema = Joi.object({
+  name: Joi.string().required(),
+});
+
+export class AuthorizationConfiguration {
+  /** @description The url to obtain the access token using the authorization code on the backend @example "http://{auth_state:store_name}.store.com/admin/oauth/authorize", "http://store.com/oauth/authorize" */
+  url_template!: string;
+  /** @description A list of query parameters that will be attached to the url */
+  query_parameters?: Parameter[];
+  /** @description Method to use when making the server-server code for token request @example "GET", "POST" */
+  method?: string;
+  /** @description List of parameters that are sent to the integration during the server-server authorization request. These are built using the content type specified in the headers array. */
+  body?: Parameter[];
+  /** @description List of headers that are sent to the integration when authorizing a token */
+  headers?: Parameter[];
+  /** @description A nonce query parameter included on the accept request, then returned and validated on the redirect request */
+  nonce?: NonceConfiguration;
+}
+
+export const AuthorizationConfigurationSchema = Joi.object({
+  url_template: Joi.string().required(),
+  query_parameters: Joi.array().optional().items(ParameterSchema),
+  method: MethodSchema.optional(),
+  body: Joi.array().optional().items(ParameterSchema),
+  headers: Joi.array().optional().items(ParameterSchema),
+  nonce: NonceConfigurationSchema.optional(),
+});

package/src/models/addresses/address-base.ts

@@ -30,4 +30,6 @@ export class AddressBase {
   is_eu?: boolean;
   /** @description Metadata for this address */
   address_metadata?: { [key: string]: string };
+  /** @description Instructions to help the carrier navigate to the address. */
+  instructions?: string;
 }

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

@@ -1,5 +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/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,5 +1,5 @@
-import { BillingLineItem } from '..';
-
+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 */
@@ -11,3 +11,10 @@ export class VoidResponse {
   /** @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(),
+});