@shipengine/connect-carrier-api 2.6.2 → 2.7.0

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

@@ -13,6 +13,8 @@ import {
   ValidateInboundDataRequest,
   NormalizeTrackingDataRequest,
   GetRelayPointsRequest,
+  GetServicePointsRequest,
+  GetServicePointRequest,
 } from '../requests';
 
 import {
@@ -29,6 +31,8 @@ import {
   ValidateInboundDataResponse,
   NormalizeTrackingDataResponse,
   GetRelayPointsResponse,
+  GetServicePointsResponse,
+  GetServicePointResponse,
 } from '../responses';
 
 import { CarrierAppMetadata } from './metadata/carrier-app-metadata';
@@ -126,4 +130,18 @@ export interface CarrierAppDefinition {
   GetRelayPoints?: (
     request: GetRelayPointsRequest,
   ) => GetRelayPointsResponse | Promise<GetRelayPointsResponse>;
+  /**
+   * @description This endpoint is used to get carrier service points
+   * @param request Data needed by the provider about the service points to be returned
+   */
+  GetServicePoints?: (
+    request: GetServicePointsRequest,
+  ) => GetServicePointsResponse | Promise<GetServicePointsResponse>;
+  /**
+   * @description This endpoint is used to get a carrier service point by id
+   * @param request Data needed by the provider about the service point to be returned
+   */
+  GetServicePoint?: (
+    request: GetServicePointRequest,
+  ) => GetServicePointResponse | Promise<GetServicePointResponse>;
 }

package/src/app/carrier-app.ts

@@ -20,6 +20,8 @@ import {
   ValidateInboundDataResponseSchema,
   NormalizeTrackingDataResponseSchema,
   GetRelayPointsResponseSchema,
+  GetServicePointsResponseSchema,
+  GetServicePointResponseSchema,
 } from '../responses';
 import { Schema } from 'joi';
 
@@ -113,6 +115,18 @@ export class CarrierApp implements ConnectRuntimeApp {
         definition.GetRelayPoints,
         GetRelayPointsResponseSchema,
       ],
+      [
+        Method.POST,
+        ApiEndpoints.GetServicePoints,
+        definition.GetServicePoints,
+        GetServicePointsResponseSchema,
+      ],
+      [
+        Method.POST,
+        ApiEndpoints.GetServicePoint,
+        definition.GetServicePoint,
+        GetServicePointResponseSchema,
+      ],
     ).forEach(([method, path, implementation, schema]) => {
       if (implementation) {
         this.routes.push({

package/src/app/constants.ts

@@ -13,4 +13,6 @@ export enum ApiEndpoints {
   ValidateInboundData = '/ValidateInboundData',
   NormalizeTrackingData = '/NormalizeTrackingData',
   GetRelayPoints = '/GetRelayPoints',
+  GetServicePoints = '/GetServicePoints',
+  GetServicePoint = '/GetServicePoint',
 }

package/src/app/metadata/service-point-feature.ts

@@ -0,0 +1,13 @@
+import Joi from 'joi';
+
+export enum ServicePointFeaturesEnum {
+  DropOffPoint = 'DropOffPoint',
+  PickupPoint = 'PickupPoint',
+  PrintServices = 'PrintServices',
+  AfterHoursLocker = 'AfterHoursLocker',
+  AfterHoursDropbox = 'AfterHoursDropbox',
+}
+
+export const ServicePointFeaturesEnumSchema = Joi.string().valid(
+  ...Object.values(ServicePointFeaturesEnum),
+);

package/src/models/addresses/service-point-address.ts

@@ -0,0 +1,8 @@
+import { LatLong } from '../tracking/lat-long';
+import { AddressBase } from './address-base';
+
+/** @description The basic address type related to service points */
+export class ServicePointAddress extends AddressBase {
+  /** @description Geographical location */
+  geo?: LatLong;
+}

package/src/models/service-points/hours-of-operation.ts

@@ -0,0 +1,14 @@
+import Joi from 'joi';
+
+/** @description Indicates a specific time window that a service point is open */
+export class HoursOfOperation {
+  /** @description The open time expressed in ISO 8601 time only format */
+  open?: string;
+  /** @description The close time expressed in ISO 8601 time only format */
+  close?: string;
+}
+
+export const HoursOfOperationSchema = Joi.object({
+  open: Joi.string().optional().empty(),
+  close: Joi.string().optional().empty(),
+});

package/src/models/service-points/index.ts

@@ -0,0 +1,3 @@
+export * from './service-point';
+export * from './weekly-hours-of-operation';
+export * from './service-point-response-address';

package/src/models/service-points/search-radius-unit.ts

@@ -0,0 +1,5 @@
+/** @description Unit of measurement for search radius */
+export enum SearchRadiusUnit {
+  Miles = 'miles',
+  Kilometers = 'kilometers',
+}

package/src/models/service-points/search-radius.ts

@@ -0,0 +1,13 @@
+import { SearchRadiusUnit } from './search-radius-unit';
+
+/** @description Basic structure for service point search radius */
+export class SearchRadius {
+  /** @description Search radius in miles */
+  radius_in_miles?: number;
+  /** @description Search radius in kilometers */
+  radius_in_kilometers?: number;
+  /** @description Search radius in the original unit */
+  source_radius?: number;
+  /** @description Search radius unit */
+  source_radius_unit!: SearchRadiusUnit;
+}

package/src/models/service-points/service-point-response-address.ts

@@ -0,0 +1,21 @@
+import Joi from 'joi';
+import { ServicePointAddress } from '../addresses/service-point-address';
+import { LatLongSchema } from '../tracking/lat-long';
+
+/** @description The address information corresponding to a specific service point */
+export class ServicePointResponseAddress extends ServicePointAddress {
+  /** @description Description of the location */
+  description?: string;
+}
+
+export const ServicePointResponseAddressSchema = Joi.object({
+  phone_number: Joi.string().optional().empty(),
+  company_name: Joi.string().optional().empty(),
+  description: Joi.string().optional().empty(),
+  geo: LatLongSchema.optional(),
+  address_lines: Joi.array().items(Joi.string()).required(),
+  city_locality: Joi.string().required(),
+  state_province: Joi.string().required(),
+  postal_code: Joi.string().required(),
+  country_code: Joi.string().required(),
+});

package/src/models/service-points/service-point.ts

@@ -0,0 +1,29 @@
+import Joi from 'joi';
+import {
+  ServicePointFeaturesEnum,
+  ServicePointFeaturesEnumSchema,
+} from '../../app/metadata/service-point-feature';
+import {
+  ServicePointResponseAddress,
+  ServicePointResponseAddressSchema,
+} from './service-point-response-address';
+import { WeeklyHoursOfOperation, WeeklyHoursOfOperationSchema } from './weekly-hours-of-operation';
+
+/** @description Basic structure for a service point */
+export class ServicePoint {
+  /** @description The identifier for the carrier's service point */
+  service_point_id!: string;
+  /** @description The address where the service point is located */
+  address!: ServicePointResponseAddress;
+  /** @description Weekly hours of operation for the service point */
+  hours_of_operation!: WeeklyHoursOfOperation;
+  /** @description Features supported by the service point */
+  features?: ServicePointFeaturesEnum[];
+}
+
+export const ServicePointSchema = Joi.object({
+  service_point_id: Joi.string().required(),
+  address: ServicePointResponseAddressSchema.required(),
+  hours_of_operation: WeeklyHoursOfOperationSchema.required(),
+  features: Joi.array().items(ServicePointFeaturesEnumSchema).optional(),
+});

package/src/models/service-points/weekly-hours-of-operation.ts

@@ -0,0 +1,23 @@
+import Joi from 'joi';
+import { HoursOfOperation, HoursOfOperationSchema } from './hours-of-operation';
+
+/** @description The times during the week that the relay point is open */
+export class WeeklyHoursOfOperation {
+  monday?: HoursOfOperation[];
+  tuesday?: HoursOfOperation[];
+  wednesday?: HoursOfOperation[];
+  thursday?: HoursOfOperation[];
+  friday?: HoursOfOperation[];
+  saturday?: HoursOfOperation[];
+  sunday?: HoursOfOperation[];
+}
+
+export const WeeklyHoursOfOperationSchema = Joi.object({
+  monday: HoursOfOperationSchema.optional(),
+  tuesday: HoursOfOperationSchema.optional(),
+  wednesday: HoursOfOperationSchema.optional(),
+  thursday: HoursOfOperationSchema.optional(),
+  friday: HoursOfOperationSchema.optional(),
+  saturday: HoursOfOperationSchema.optional(),
+  sunday: HoursOfOperationSchema.optional(),
+});

package/src/requests/get-service-point-request.ts

@@ -0,0 +1,9 @@
+import { BaseRequest } from './base-request';
+
+/** @description Basic structure for a request to get a single service point by id */
+export class GetServicePointRequest extends BaseRequest {
+  /** @description The service point id to get */
+  service_point_id!: string;
+  /** @description The two character country code of the service point. The codes are specified by ISO 3166-1 alpha-2 */
+  country_code!: string;
+}

package/src/requests/get-service-points-request.ts

@@ -0,0 +1,15 @@
+import { ServicePointAddress } from '../models/addresses/service-point-address';
+import { SearchRadius } from '../models/service-points/search-radius';
+import { BaseRequest } from './base-request';
+
+/** @description Basic structure for a request to get service points */
+export class GetServicePointsRequest extends BaseRequest {
+  /** @description The service code uniquely identifies a shipping service */
+  service_code?: string;
+  /** @description The address input for searching nearby carrier service points */
+  address!: ServicePointAddress;
+  /** @description The desired search radius around the given address */
+  search_radius?: SearchRadius;
+  /** @description The maximum number of service points to return */
+  max_results?: number;
+}

package/src/requests/index.ts

@@ -12,3 +12,5 @@ export * from './cancel-notification-request';
 export * from './validate-inbound-data-request';
 export * from './normalize-tracking-data-request';
 export * from './get-relay-points-request';
+export * from './get-service-points-request';
+export * from './get-service-point-request';

package/src/responses/get-service-point-response.ts

@@ -0,0 +1,12 @@
+import { BaseResponse, BaseResponseSchema } from './base-response';
+import { ServicePoint, ServicePointSchema } from '../models/service-points';
+
+/** @description Basic structure for a response to get a single service point by id */
+export class GetServicePointResponse extends BaseResponse {
+  /** @description The resulting service point */
+  service_point!: ServicePoint;
+}
+
+export const GetServicePointResponseSchema = BaseResponseSchema.keys({
+  service_point: ServicePointSchema.required(),
+});

package/src/responses/get-service-points-response.ts

@@ -0,0 +1,13 @@
+import { BaseResponse, BaseResponseSchema } from './base-response';
+import Joi from 'joi';
+import { ServicePoint, ServicePointSchema } from '../models/service-points';
+
+/** @description Basic structure for a response to get service points */
+export class GetServicePointsResponse extends BaseResponse {
+  /** @description The resulting service points */
+  service_points!: ServicePoint[];
+}
+
+export const GetServicePointsResponseSchema = BaseResponseSchema.keys({
+  service_points: Joi.array().required().items(ServicePointSchema),
+});

package/src/responses/index.ts

@@ -12,3 +12,5 @@ export * from './create-notification-response';
 export * from './validate-inbound-data-response';
 export * from './normalize-tracking-data-response';
 export * from './get-relay-points-response';
+export * from './get-service-points-response';
+export * from './get-service-point-response';