@shipengine/connect-carrier-api 4.17.0-beta → 4.18.0

package/lib/responses/upload-documents-response-schema.d.ts

@@ -0,0 +1,2 @@
+import Joi from 'joi';
+export declare const UploadDocumentsResponseSchema: Joi.ObjectSchema<any>;

package/lib/responses/upload-documents-response-schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadDocumentsResponseSchema = void 0;
+const tslib_1 = require("tslib");
+const joi_1 = tslib_1.__importDefault(require("joi"));
+const upload_document_result_schema_1 = require("./upload-document-result-schema");
+exports.UploadDocumentsResponseSchema = joi_1.default.object({
+    metadata: joi_1.default.object().pattern(/.*/, [joi_1.default.any()]).required(),
+    documents: joi_1.default.array().required().min(1).items(upload_document_result_schema_1.UploadDocumentResultSchema),
+});
+//# sourceMappingURL=upload-documents-response-schema.js.map

package/lib/responses/upload-documents-response-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-documents-response-schema.js","sourceRoot":"","sources":["../../src/responses/upload-documents-response-schema.ts"],"names":[],"mappings":";;;;AAAA,sDAAsB;AACtB,mFAA6E;AAEhE,QAAA,6BAA6B,GAAG,aAAG,CAAC,MAAM,CAAC;IACtD,QAAQ,EAAE,aAAG,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,aAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5D,SAAS,EAAE,aAAG,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,0DAA0B,CAAC;CAC3E,CAAC,CAAC"}

package/lib/responses/upload-documents-response.d.ts

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

package/lib/responses/upload-documents-response.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadDocumentsResponse = void 0;
+const base_response_1 = require("./base-response");
+/**
+ * Response for uploading documents to a carrier.
+ */
+class UploadDocumentsResponse extends base_response_1.BaseResponse {
+    documents;
+}
+exports.UploadDocumentsResponse = UploadDocumentsResponse;
+//# sourceMappingURL=upload-documents-response.js.map

package/lib/responses/upload-documents-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-documents-response.js","sourceRoot":"","sources":["../../src/responses/upload-documents-response.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAG/C;;GAEG;AACH,MAAa,uBAAwB,SAAQ,4BAAY;IACvD,SAAS,CAA0B;CACpC;AAFD,0DAEC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipengine/connect-carrier-api",
-  "version": "4.17.0-beta",
+  "version": "4.18.0",
   "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.29.0"
+    "version": "1.30.0"
   },
   "paths": {
     "/Register": {
@@ -947,6 +947,53 @@
         }
       }
     },
+    "/StartTracking": {
+      "post": {
+        "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": {
+          "description": "An object containing identifiers to subscribe to tracking events for.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/StartTrackingRequest"
+              },
+              "example": {
+                "identifiers": [
+                  {
+                    "type": "tracking_number",
+                    "value": "PL1234567890"
+                  },
+                  {
+                    "type": "tracking_number",
+                    "value": "PL0987654321"
+                  }
+                ],
+                "transaction_id": "771323cb-75eb-4e2a-bc11-fda608c6ade8",
+                "authorization": {},
+                "metadata": {},
+                "connection_name": "a_connect_connection_name_string"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful subscription response with results for each identifier.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StartTrackingResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/UpdateSettings": {
       "post": {
         "tags": [
@@ -1209,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": {},
@@ -3829,7 +3880,7 @@
             "items": {
               "$ref": "#/components/schemas/DisplayScheme"
             },
-            "description": "Label display scheme.",
+            "description": "Display schemes for shipments.",
             "nullable": true
           }
         },
@@ -4411,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": {
@@ -5383,6 +5490,83 @@
         "additionalProperties": false,
         "description": "This model represents the successful response from a tracking request."
       },
+      "StartTrackingRequest": {
+        "required": [
+          "identifiers",
+          "transaction_id"
+        ],
+        "type": "object",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRequest"
+          }
+        ],
+        "properties": {
+          "identifiers": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/TrackingIdentifier"
+            },
+            "description": "Array of identifiers (e.g., tracking numbers) to subscribe to tracking events for.",
+            "nullable": false
+          }
+        },
+        "additionalProperties": false,
+        "description": "This model represents the request payload for subscribing to tracking events for one or more identifiers."
+      },
+      "StartTrackingResponse": {
+        "required": [
+          "subscription_results"
+        ],
+        "type": "object",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseResponse"
+          }
+        ],
+        "properties": {
+          "subscription_results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SubscriptionResult"
+            },
+            "description": "Array of subscription results, one for each identifier in the request.",
+            "nullable": false
+          }
+        },
+        "additionalProperties": false,
+        "description": "This model represents the response from a start tracking subscription request."
+      },
+      "SubscriptionResult": {
+        "required": [
+          "identifier",
+          "status"
+        ],
+        "type": "object",
+        "properties": {
+          "identifier": {
+            "$ref": "#/components/schemas/TrackingIdentifier"
+          },
+          "status": {
+            "$ref": "#/components/schemas/SubscriptionStatus"
+          },
+          "message": {
+            "type": "string",
+            "description": "Optional message providing additional details about the subscription result.",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "This model represents the result of a tracking subscription attempt for a single identifier."
+      },
+      "SubscriptionStatus": {
+        "enum": [
+          "success",
+          "failed"
+        ],
+        "type": "string",
+        "description": "Status of the tracking subscription attempt.\nsuccess - Subscription was successful\nfailed - Subscription failed"
+      },
       "TransportMeanEnum": {
         "enum": [
           "ground",
@@ -5479,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"

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

@@ -20,6 +20,7 @@ import {
   ImportTrackingEventsRequest,
   UpdateSettingsRequest,
   ListPickupsRequest,
+  StartTrackingRequest,
 } from '../requests';
 
 import {
@@ -40,17 +41,27 @@ import {
   GetServicePointResponse,
   UpdateSettingsResponse,
   ListPickupsResponse,
+  StartTrackingResponse,
 } from '../responses';
 
 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
@@ -183,6 +194,13 @@ export interface CarrierAppDefinition {
   UpdateSettings?: (
     request: UpdateSettingsRequest,
   ) => UpdateSettingsResponse | Promise<UpdateSettingsResponse>;
+  /**
+   * @description This endpoint is used to subscribe for status updates from the carrier
+   * @param request Data needed by the provider to start tracking shipments
+   */
+  StartTracking?: (
+    request: StartTrackingRequest,
+  ) => StartTrackingResponse | Promise<StartTrackingResponse>;
   /**
    * @description A collection of additional routes that can be used to extend the functionality of the app.
    * Extension methods are not automatically called by the ShipEngine platform, and require working with Auctane developers to implement.

package/src/app/constants.ts

@@ -18,4 +18,6 @@ export enum ApiEndpoints {
   ImportTrackingEvents = '/ImportTrackingEvents',
   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],
@@ -26,5 +27,6 @@ export const createEndpointMapping = (
   [Method.POST, ApiEndpoints.ImportTrackingEvents, definition.ImportTrackingEvents],
   [Method.POST, ApiEndpoints.UpdateSettings, definition.UpdateSettings],
   [Method.POST, ApiEndpoints.ListPickups, definition.ListPickups],
+  [Method.POST, ApiEndpoints.StartTracking, definition.StartTracking],
   ...mapExtensions(definition.Extensions),
 ];

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/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/models/tracking/index.ts

@@ -16,3 +16,5 @@ export * from './update-method-schema';
 export * from './update-method';
 export * from './standardized-status-detail-codes';
 export * from './standardized-status-detail-codes-schema';
+export * from './start-tracking-status';
+export * from './start-tracking-status-schema';

package/src/models/tracking/start-tracking-status-schema.ts

@@ -0,0 +1,6 @@
+import Joi from 'joi';
+import { StartTrackingStatus } from './start-tracking-status';
+
+export const SubscriptionStatusSchema = Joi.string()
+  .valid(...Object.values(StartTrackingStatus))
+  .required();

package/src/models/tracking/start-tracking-status.ts

@@ -0,0 +1,7 @@
+/** Status of subscription results */
+export enum StartTrackingStatus {
+  /** @description The tracking subscription was created successfully */
+  SUCCESS = 'SUCCESS',
+  /** @description The tracking subscription could not be created */
+  FAILED = 'FAILED',
+}

package/src/requests/index.ts

@@ -17,3 +17,6 @@ export * from './tracking-request';
 export * from './validate-inbound-data-request';
 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/start-tracking-request-schema.ts

@@ -0,0 +1,7 @@
+import Joi from 'joi';
+import { IdentifierSchema } from '../models/identifier-schema';
+import { BaseRequestSchema } from './base-request-schema';
+
+export const StartTrackingRequestSchema = BaseRequestSchema.keys({
+  identifiers: Joi.array().required().items(IdentifierSchema),
+});

package/src/requests/start-tracking-request.ts

@@ -0,0 +1,9 @@
+import { BaseRequest } from './base-request';
+import { Identifier } from '../models/identifier';
+
+/**
+ * @description Request to start tracking shipments using identifiers
+ */
+export class StartTrackingRequest extends BaseRequest {
+  identifiers!: Identifier[];
+}

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/index.ts

@@ -33,3 +33,9 @@ export * from './void-labels-response-schema';
 export * from './void-labels-response';
 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

@@ -0,0 +1,14 @@
+import Joi from 'joi';
+import { IdentifierSchema } from '../models/identifier-schema';
+import { BaseResponseSchema } from './base-response-schema';
+import { SubscriptionStatusSchema } from '../models/tracking/start-tracking-status-schema';
+
+export const SubscriptionResultSchema = Joi.object({
+  identifier: IdentifierSchema.required(),
+  status: SubscriptionStatusSchema,
+  message: Joi.string().required(),
+});
+
+export const StartTrackingResponseSchema = BaseResponseSchema.keys({
+  subscription_results: Joi.array().required().items(SubscriptionResultSchema),
+});

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

@@ -0,0 +1,16 @@
+import { BaseResponse } from './base-response';
+import { Identifier } from '../models';
+import { StartTrackingStatus } from '../models/tracking/start-tracking-status';
+
+/**
+ * @description Response from start tracking subscriptions
+ */
+export class StartTrackingResponse extends BaseResponse {
+  subscription_results!: SubscriptionResult[];
+}
+
+export interface SubscriptionResult {
+  identifier: Identifier;
+  status: StartTrackingStatus;
+  message: string;
+}