@shipengine/connect-carrier-api 4.17.4 → 4.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipengine/connect-carrier-api",
-  "version": "4.17.4",
+  "version": "4.18.1",
   "description": "This is the typescript/javascript definitions for carrier api",
   "homepage": "https://connect.shipengine.com",
   "main": "./lib/index.js",

package/spec.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Shipping API",
     "description": "This API specification describes the canonical ShipEngine Shipping API connector module.",
-    "version": "1.28.10"
+    "version": "1.30.1"
   },
   "paths": {
     "/Register": {
@@ -949,7 +949,9 @@
     },
     "/StartTracking": {
       "post": {
-        "tags": ["Tracking"],
+        "tags": [
+          "Tracking"
+        ],
         "description": "This method subscribes to tracking events for one or more identifiers. This endpoint initiate the subscription with the carrier's system.",
         "operationId": "StartTracking",
         "requestBody": {
@@ -961,8 +963,14 @@
               },
               "example": {
                 "identifiers": [
-                  { "type": "tracking_number", "value": "PL1234567890" },
-                  { "type": "tracking_number", "value": "PL0987654321" }
+                  {
+                    "type": "tracking_number",
+                    "value": "PL1234567890"
+                  },
+                  {
+                    "type": "tracking_number",
+                    "value": "PL0987654321"
+                  }
                 ],
                 "transaction_id": "771323cb-75eb-4e2a-bc11-fda608c6ade8",
                 "authorization": {},
@@ -1248,6 +1256,10 @@
           },
           "transport_mean": {
             "$ref": "#/components/schemas/TransportMeanEnum"
+          },
+          "enable_document_upload": {
+            "type": "boolean",
+            "description": "Indicates whether document upload is enabled for the shipment."
           }
         },
         "additionalProperties": {},
@@ -1858,6 +1870,14 @@
             "description": "Alternative identifiers associated with this shipment.",
             "nullable": true
           },
+          "limit_identifiers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/LimitIdentifier"
+            },
+            "description": "An array that defines rate/usage limit identifiers applicable to specific functionalities within the integration. Each entry represents a unique limit configuration tied to a functionality (e.g., \"track,\" \"createLabel\").",
+            "nullable": true
+          },
           "estimated_delivery_datetime": {
             "type": "string",
             "description": "The estimated date and time for when the shipment will be delivered. Formatted per the\r\nhttps://tools.ietf.org/html/rfc3339 spec.",
@@ -3111,6 +3131,29 @@
         "additionalProperties": false,
         "description": "A key value pair, allowing custom properties to be stored."
       },
+      "LimitIdentifier": {
+        "required": [
+          "type",
+          "value"
+        ],
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/LimitIdentifierType"
+          },
+          "value": {
+            "type": "string",
+            "description": "A unique identifier referencing the specific rate/usage limit configuration in the Rate Limiter."
+          }
+        }
+      },
+      "LimitIdentifierType": {
+        "type": "string",
+        "description": "The name of the functionality associated with this limit (e.g., \"track\").",
+        "enum": [
+          "track"
+        ]
+      },
       "ImportTrackingEventsRequest": {
         "required": [
           "transaction_id"
@@ -3837,7 +3880,7 @@
             "items": {
               "$ref": "#/components/schemas/DisplayScheme"
             },
-            "description": "Label display scheme.",
+            "description": "Display schemes for shipments.",
             "nullable": true
           }
         },
@@ -4419,6 +4462,62 @@
         ],
         "type": "string"
       },
+      "SellerDocument": {
+        "type": "object",
+        "properties": {
+          "document_upload_id": {
+            "type": "string",
+            "nullable": true
+          },
+          "type": {
+            "type": "string",
+            "description": "Standardized document format.",
+            "nullable": true
+          },
+          "name": {
+            "type": "string",
+            "description": "The document name.",
+            "nullable": true
+          },
+          "content": {
+            "type": "string",
+            "description": "Document content in base64 format.",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "Represents a document in the upload request."
+      },
+      "SellerDocumentResult": {
+        "type": "object",
+        "properties": {
+          "document_upload_id": {
+            "type": "string",
+            "nullable": true
+          },
+          "carrier_document_id": {
+            "type": "string",
+            "description": "The document ID in the carrier's system.",
+            "nullable": true
+          },
+          "uploaded_to_carrier_at": {
+            "type": "string",
+            "description": "The UTC timestamp of when the document was successfully uploaded to the carrier.",
+            "format": "date-time",
+            "nullable": true
+          },
+          "errors": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The errors that occurred while uploading a document.",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "Represents the result of uploading a document to the carrier."
+      },
       "Service": {
         "type": "object",
         "properties": {
@@ -5392,7 +5491,10 @@
         "description": "This model represents the successful response from a tracking request."
       },
       "StartTrackingRequest": {
-        "required": ["identifiers", "transaction_id"],
+        "required": [
+          "identifiers",
+          "transaction_id"
+        ],
         "type": "object",
         "allOf": [
           {
@@ -5413,7 +5515,9 @@
         "description": "This model represents the request payload for subscribing to tracking events for one or more identifiers."
       },
       "StartTrackingResponse": {
-        "required": ["subscription_results"],
+        "required": [
+          "subscription_results"
+        ],
         "type": "object",
         "allOf": [
           {
@@ -5434,7 +5538,10 @@
         "description": "This model represents the response from a start tracking subscription request."
       },
       "SubscriptionResult": {
-        "required": ["identifier", "status"],
+        "required": [
+          "identifier",
+          "status"
+        ],
         "type": "object",
         "properties": {
           "identifier": {
@@ -5443,7 +5550,7 @@
           "status": {
             "$ref": "#/components/schemas/SubscriptionStatus"
           },
-          "message": {
+          "error_message": {
             "type": "string",
             "description": "Optional message providing additional details about the subscription result.",
             "nullable": true
@@ -5453,7 +5560,10 @@
         "description": "This model represents the result of a tracking subscription attempt for a single identifier."
       },
       "SubscriptionStatus": {
-        "enum": ["success", "failed"],
+        "enum": [
+          "success",
+          "failed"
+        ],
         "type": "string",
         "description": "Status of the tracking subscription attempt.\nsuccess - Subscription was successful\nfailed - Subscription failed"
       },
@@ -5553,6 +5663,97 @@
         "additionalProperties": false,
         "description": "This model represents the successful response for updating carrier settings request."
       },
+      "UploadDocumentsRequest": {
+        "required": [
+          "documents",
+          "ship_from",
+          "transaction_id"
+        ],
+        "type": "object",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRequest"
+          }
+        ],
+        "properties": {
+          "documents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SellerDocument"
+            },
+            "description": "An array of objects, one for each successfully processed document.",
+            "nullable": true
+          },
+          "ship_from": {
+            "$ref": "#/components/schemas/ShipFrom"
+          },
+          "tracking_number": {
+            "type": "string",
+            "description": "The carrier tracking number for this shipment",
+            "nullable": true
+          },
+          "ship_to": {
+            "$ref": "#/components/schemas/ShipTo"
+          },
+          "alternative_identifiers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Identifier"
+            },
+            "description": "Alternative identifiers associated with this package",
+            "nullable": true
+          },
+          "service_code": {
+            "type": "string",
+            "description": "The service code used for this shipment",
+            "nullable": true
+          },
+          "packages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ShippedPackage"
+            },
+            "description": "The list of packages associated with this shipment",
+            "nullable": true
+          },
+          "advanced_options": {
+            "$ref": "#/components/schemas/AdvancedOptions"
+          },
+          "pickup_location": {
+            "$ref": "#/components/schemas/PudoLocation"
+          },
+          "dropoff_location": {
+            "$ref": "#/components/schemas/PudoLocation"
+          },
+          "reference": {
+            "type": "string",
+            "description": "User specified free form string to identify shipment in their own system",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "A request to upload documents for a shipment."
+      },
+      "UploadDocumentsResponse": {
+        "type": "object",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseResponse"
+          }
+        ],
+        "properties": {
+          "documents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SellerDocumentResult"
+            },
+            "description": "An array of objects, one for each successfully processed document.",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "Response for uploading documents to a carrier."
+      },
       "ValidateInboundDataRequest": {
         "required": [
           "transaction_id"
@@ -5943,4 +6144,4 @@
       "description": "Given inbound data, such as a webhook with tracking updates, return normalized information."
     }
   ]
-}
+}

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

@@ -47,12 +47,21 @@ import {
 import { CarrierAppMetadata } from './metadata/carrier-app-metadata';
 
 import { RequestResponseInfo, Handler } from '@shipengine/connect-runtime';
+import { UploadDocumentsRequest } from '../requests/upload-documents-request';
+import { UploadDocumentsResponse } from '../responses/upload-documents-response';
 
 /**
  * @description This defines a connect carrier app
  */
 export interface CarrierAppDefinition {
   Metadata: CarrierAppMetadata;
+  /**
+   * @description This method is used to upload documents to carrier
+   * @param request Data needed by the provider to upload documents
+   */
+  UploadDocuments?: (
+    request: UploadDocumentsRequest,
+  ) => UploadDocumentsResponse | Promise<UploadDocumentsResponse>;
   /**
    * @description This method is used to register an account
    * @param request The information needed to register or initialize a connection with the shipping provider

package/src/app/constants.ts

@@ -19,4 +19,5 @@ export enum ApiEndpoints {
   UpdateSettings = '/UpdateSettings',
   ListPickups = '/ListPickups',
   StartTracking = '/StartTracking',
+  UploadDocuments = '/UploadDocuments',
 }

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

@@ -10,6 +10,7 @@ export const createEndpointMapping = (
   [Method.POST, ApiEndpoints.CancelNotification, definition.CancelNotification],
   [Method.POST, ApiEndpoints.CancelPickup, definition.CancelPickup],
   [Method.POST, ApiEndpoints.CreateLabel, definition.CreateLabel],
+  [Method.POST, ApiEndpoints.UploadDocuments, definition.UploadDocuments],
   [Method.POST, ApiEndpoints.CreateManifest, definition.CreateManifest],
   [Method.POST, ApiEndpoints.GetManifest, definition.GetManifest],
   [Method.POST, ApiEndpoints.CreateNotification, definition.CreateNotification],

package/src/app/metadata/shipping-option.ts

@@ -44,6 +44,7 @@ export enum ShippingOptionEnum {
   CarrierInsurance = 'carrier-insurance',
   WindsorFrameworkMovementIndicator = 'windsor-framework-movement-indicator',
   WindsorFrameworkNotAtRisk = 'windsor-framework-not-at-risk',
+  EnableDocumentUpload = 'enable-document-upload',
 }
 
 export const ShippingOptionDictionarySchema = Joi.object(

package/src/models/advanced-options.ts

@@ -9,6 +9,8 @@ import { TransportMeanTypes } from './dangerous-good/transport-mean-types';
 
 /** @description Basic structure for shipping options */
 export class AdvancedOptions {
+  /** @description Whether the user will upload documents */
+  enable_document_upload?: boolean;
   /** @description Whether the shipment contains alcohol */
   contains_alcohol?: boolean;
   /** @description Whether the shipment does not require postage */

package/src/models/index.ts

@@ -33,5 +33,6 @@ export * from './time-window-schema';
 export * from './time-window';
 export * from './tracking';
 export * from './units';
+export * from './seller-documents';
 export * from './bill-to';
 export * from './labels/paperless-details';

package/src/models/limit-identifier-schema.ts

@@ -0,0 +1,7 @@
+import Joi from 'joi';
+import { LimitIdentifierTypeSchema } from './limit-identifier-type-schema';
+
+export const LimitIdentifierSchema = Joi.object({
+  type: LimitIdentifierTypeSchema.required(),
+  value: Joi.string().required(),
+});

package/src/models/limit-identifier-type-schema.ts

@@ -0,0 +1,4 @@
+import Joi from 'joi';
+import { LimitIdentifierType } from './limit-identifier-type';
+
+export const LimitIdentifierTypeSchema = Joi.string().valid(...Object.values(LimitIdentifierType));

package/src/models/limit-identifier-type.ts

@@ -0,0 +1,3 @@
+export enum LimitIdentifierType {
+  Track = 'track',
+}

package/src/models/limit-identifier.ts

@@ -0,0 +1,6 @@
+import { LimitIdentifierType } from './limit-identifier-type';
+
+export class LimitIdentifier {
+  type!: LimitIdentifierType;
+  value!: string;
+}

package/src/models/seller-documents/index.ts

@@ -0,0 +1,2 @@
+export * from './seller-document';
+export * from './seller-documents-schema';

package/src/models/seller-documents/seller-document.ts

@@ -0,0 +1,12 @@
+import { ShipFrom } from '..';
+import { ShippedShipment } from '../pickup/shipped-shipment';
+
+/**
+ * Represents a document in the upload request.
+ */
+export class SellerDocument {
+  document_upload_id!: string;
+  type!: string;
+  name!: string;
+  content!: string;
+}

package/src/models/seller-documents/seller-documents-schema.ts

@@ -0,0 +1,13 @@
+import Joi from 'joi';
+
+/**
+ * Joi validation schema for SellerDocument
+ */
+export const SellerDocumentSchema = Joi.object({
+  document_upload_id: Joi.string().required().empty(''),
+  type: Joi.string().required().empty(''),
+  name: Joi.string().required().empty(''),
+  content: Joi.string().required().empty(''),
+  ship_from: Joi.object().required(),
+  ship_to: Joi.object().required(),
+});

package/src/requests/index.ts

@@ -19,3 +19,4 @@ export * from './void-labels-request';
 export * from './update-settings-request';
 export * from './start-tracking-request';
 export * from './start-tracking-request-schema';
+export * from './upload-documents-request';

package/src/requests/upload-documents-request.ts

@@ -0,0 +1,38 @@
+import { BaseRequest } from './base-request';
+import {
+  AdvancedOptions,
+  Identifier,
+  PudoLocation,
+  SellerDocument,
+  ShipFrom,
+  ShippedPackage,
+  ShipTo,
+} from '../models';
+
+/**
+ * A request to upload documents for a shipment.
+ */
+export class UploadDocumentsRequest extends BaseRequest {
+  /** @description The list of documents to be uploaded */
+  documents!: SellerDocument[];
+  /** @description The carrier tracking number for this shipment */
+  tracking_number!: string;
+  /** @description The shipment sender's address. It may or may not have been validated.  */
+  ship_from?: ShipFrom;
+  /** @description The address that a shipment will be delivered to */
+  ship_to?: ShipTo;
+  /** @description Non-tracking alternative ids associated with this shipment */
+  alternative_identifiers?: Identifier[];
+  /** @description The service code used for this shipment */
+  service_code?: string;
+  /** @description The list of packages associated with this shipment */
+  packages?: ShippedPackage[];
+  /** @description Advanced shipping options (Contains Alcohol, Non Machinable, etc) */
+  advanced_options?: AdvancedOptions;
+  /** @description Add pick-up location detail*/
+  pickup_location?: PudoLocation;
+  /** @description Add drop-off location detail*/
+  dropoff_location?: PudoLocation;
+  /** @description User specified free form string to identify shipment in their own system */
+  reference?: string;
+}

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

@@ -10,6 +10,7 @@ import { RelayPointDetailsSchema } from '../models/relay-points/relay-point-deta
 import { TimeWindowSchema } from '../models/time-window-schema';
 import { PaperlessDetailsSchema } from '../models/labels/paperless-details-schema';
 import { PudoLocationSchema } from '../models/addresses/pudo-location-schema';
+import { LimitIdentifierSchema } from '../models/limit-identifier-schema';
 
 export const CreateLabelResponseSchema = BaseResponseSchema.keys({
   transaction_id: Joi.string().required(),
@@ -30,4 +31,5 @@ export const CreateLabelResponseSchema = BaseResponseSchema.keys({
   relay_points: RelayPointDetailsSchema.optional(),
   dropoff_location: PudoLocationSchema.optional(),
   pickup_location: PudoLocationSchema.optional(),
+  limit_identifiers: Joi.array().optional().items(LimitIdentifierSchema),
 });

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

@@ -12,6 +12,7 @@ import {
   PudoLocation,
 } from '../models';
 import { CarrierWeight } from '../models/units/carrier-weight';
+import { LimitIdentifier } from '../models/limit-identifier';
 
 /** @description Basic structure for a response to create a label */
 export class CreateLabelResponse extends BaseResponse {
@@ -36,4 +37,5 @@ export class CreateLabelResponse extends BaseResponse {
   dropoff_location?: PudoLocation;
   pickup_location?: PudoLocation;
   carrier_weight?: CarrierWeight;
+  limit_identifiers?: LimitIdentifier[];
 }

package/src/responses/index.ts

@@ -35,3 +35,7 @@ export * from './update-settings-response-schema';
 export * from './update-settings-response';
 export * from './start-tracking-response';
 export * from './start-tracking-response-schema';
+export * from './seller-document-result';
+export * from './upload-document-result-schema';
+export * from './upload-documents-response-schema';
+export * from './upload-documents-response';

package/src/responses/seller-document-result.ts

@@ -0,0 +1,9 @@
+/**
+ * Represents the result of uploading a document to the carrier.
+ */
+export class SellerDocumentResult {
+  document_upload_id!: string;
+  carrier_document_id?: string;
+  uploaded_to_carrier_at?: Date;
+  errors?: string[];
+}

package/src/responses/start-tracking-response-schema.ts

@@ -6,7 +6,7 @@ import { SubscriptionStatusSchema } from '../models/tracking/start-tracking-stat
 export const SubscriptionResultSchema = Joi.object({
   identifier: IdentifierSchema.required(),
   status: SubscriptionStatusSchema,
-  message: Joi.string().required(),
+  error_message: Joi.string().allow('').optional(),
 });
 
 export const StartTrackingResponseSchema = BaseResponseSchema.keys({

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

@@ -12,5 +12,5 @@ export class StartTrackingResponse extends BaseResponse {
 export interface SubscriptionResult {
   identifier: Identifier;
   status: StartTrackingStatus;
-  message: string;
+  error_message: string;
 }

package/src/responses/upload-document-result-schema.ts

@@ -0,0 +1,8 @@
+import Joi from 'joi';
+
+export const UploadDocumentResultSchema = Joi.object({
+  document_upload_id: Joi.string().required().empty(''),
+  carrier_document_id: Joi.string().optional().empty(''),
+  uploaded_to_carrier_at: Joi.string().optional().isoDate(),
+  errors: Joi.array().items(Joi.string()).optional(),
+});

package/src/responses/upload-documents-response-schema.ts

@@ -0,0 +1,7 @@
+import Joi from 'joi';
+import { UploadDocumentResultSchema } from './upload-document-result-schema';
+
+export const UploadDocumentsResponseSchema = Joi.object({
+  metadata: Joi.object().pattern(/.*/, [Joi.any()]).required(),
+  documents: Joi.array().required().min(1).items(UploadDocumentResultSchema),
+});

package/src/responses/upload-documents-response.ts

@@ -0,0 +1,9 @@
+import { BaseResponse } from './base-response';
+import { SellerDocumentResult } from './seller-document-result';
+
+/**
+ * Response for uploading documents to a carrier.
+ */
+export class UploadDocumentsResponse extends BaseResponse {
+  documents?: SellerDocumentResult[];
+}