[feat] Add SmartRate endpoints functions

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds new `EstimateDeliveryDateForShipment`, `EstimateDeliveryDateForZipPair`, `RecommendShipDateForShipment` and `RecommendShipDateForZipPair`
+  - Existing `GetShipmentEstimatedDeliveryDate` marked as deprecated in favor of `EstimateDeliveryDateForShipment`
+
 ## v4.3.1 (2024-07-01)
 
 - Adds missing `Readable` and `Logo` fields to `CarrierType` struct

shipment.go

@@ -125,6 +125,28 @@ type EstimatedDeliveryDate struct {
 	Rate                      SmartRate                 `json:"rate,omitempty"`
 }
 
+// EstimateDeliveryDateForShipmentResult is the result of the EstimateDeliveryDateForShipment method.
+type EstimateDeliveryDateForShipmentResult struct {
+	Rate                 *SmartRate                           `json:"rate,omitempty"`
+	TimeInTransitDetails *TimeInTransitDetailsForDeliveryDate `json:"easypost_time_in_transit_data,omitempty"`
+}
+
+// EstimateDeliveryDateForShipmentParams are used in the EstimateDeliveryDateForShipment method.
+type EstimateDeliveryDateForShipmentParams struct {
+	PlannedShipDate string `json:"planned_ship_date,omitempty"`
+}
+
+// RecommendShipDateForShipmentResult is the result of the RecommendShipDateForShipment method.
+type RecommendShipDateForShipmentResult struct {
+	Rate                 *SmartRate                       `json:"rate,omitempty"`
+	TimeInTransitDetails *TimeInTransitDetailsForShipDate `json:"easypost_time_in_transit_data,omitempty"`
+}
+
+// RecommendShipDateForShipmentParams are used in the RecommendShipDateForShipment method.
+type RecommendShipDateForShipmentParams struct {
+	DesiredDeliveryDate string `json:"desired_delivery_date,omitempty"`
+}
+
 // CreateShipment creates a new Shipment object. The ToAddress, FromAddress and
 // Parcel attributes are required. These objects may be fully-specified to
 // create new ones at the same time as creating the Shipment, or they can refer
@@ -386,12 +408,14 @@ func (c *Client) GenerateShipmentFormWithOptionsWithContext(ctx context.Context,
 }
 
 // GetShipmentEstimatedDeliveryDate retrieves the estimated delivery date of each Rate via SmartRate.
-func (c *Client) GetShipmentEstimatedDeliveryDate(shipmentID, plannedShipDate string) (out []*EstimatedDeliveryDate, err error) {
+// Deprecated: Use EstimateDeliveryDateForShipment instead. This method will be removed in a future release.
+func (c *Client) GetShipmentEstimatedDeliveryDate(shipmentID string, plannedShipDate string) (out []*EstimatedDeliveryDate, err error) {
 	return c.GetShipmentEstimatedDeliveryDateWithContext(context.Background(), shipmentID, plannedShipDate)
 }
 
 // GetShipmentEstimatedDeliveryDateWithContext performs the same operation as GetShipmentEstimatedDeliveryDate,
 // but allows specifying a context that can interrupt the request.
+// Deprecated: Use EstimateDeliveryDateForShipmentWithContext instead. This method will be removed in a future release.
 func (c *Client) GetShipmentEstimatedDeliveryDateWithContext(ctx context.Context, shipmentID string, plannedShipDate string) (out []*EstimatedDeliveryDate, err error) {
 	vals := url.Values{"planned_ship_date": []string{plannedShipDate}}
 	res := struct {
@@ -400,3 +424,31 @@ func (c *Client) GetShipmentEstimatedDeliveryDateWithContext(ctx context.Context
 	err = c.do(ctx, http.MethodGet, "shipments/"+shipmentID+"/smartrate/delivery_date", vals, &res)
 	return
 }
+
+// EstimateDeliveryDateForShipment retrieves the estimated delivery date of each rate for a Shipment via the Delivery Date Estimator API, based on a specific ship date.
+func (c *Client) EstimateDeliveryDateForShipment(shipmentID string, params *EstimateDeliveryDateForShipmentParams) (out []*EstimateDeliveryDateForShipmentResult, err error) {
+	return c.EstimateDeliveryDateForShipmentWithContext(context.Background(), shipmentID, params)
+}
+
+// EstimateDeliveryDateForShipmentWithContext performs the same operation as EstimateDeliveryDateForShipment, but allows specifying a context that can interrupt the request.
+func (c *Client) EstimateDeliveryDateForShipmentWithContext(ctx context.Context, shipmentID string, params *EstimateDeliveryDateForShipmentParams) (out []*EstimateDeliveryDateForShipmentResult, err error) {
+	res := struct {
+		Results *[]*EstimateDeliveryDateForShipmentResult `json:"rates,omitempty"`
+	}{Results: &out}
+	err = c.do(ctx, http.MethodGet, "shipments/"+shipmentID+"/smartrate/delivery_date", params, &res)
+	return
+}
+
+// RecommendShipDateForShipment retrieves the recommended ship date of each rate for a Shipment via the Precision Shipping API, based on a specific desired delivery date.
+func (c *Client) RecommendShipDateForShipment(shipmentID string, params *RecommendShipDateForShipmentParams) (out []*RecommendShipDateForShipmentResult, err error) {
+	return c.RecommendShipDateForShipmentWithContext(context.Background(), shipmentID, params)
+}
+
+// RecommendShipDateForShipmentWithContext performs the same operation as RecommendShipDateForShipment, but allows specifying a context that can interrupt the request.
+func (c *Client) RecommendShipDateForShipmentWithContext(ctx context.Context, shipmentID string, params *RecommendShipDateForShipmentParams) (out []*RecommendShipDateForShipmentResult, err error) {
+	res := struct {
+		Results *[]*RecommendShipDateForShipmentResult `json:"rates,omitempty"`
+	}{Results: &out}
+	err = c.do(ctx, http.MethodGet, "shipments/"+shipmentID+"/smartrate/precision_shipping", params, &res)
+	return
+}

smart_rate.go

@@ -0,0 +1,95 @@
+package easypost
+
+import (
+	"context"
+)
+
+// TimeInTransitDetailsForDeliveryDate contains the time-in-transit details and estimated delivery date for a specific DeliveryDateForZipPairEstimate or EstimateDeliveryDateForShipmentResult.
+type TimeInTransitDetailsForDeliveryDate struct {
+	PlannedShipDate               *DateTime      `json:"planned_ship_date,omitempty"`
+	EasyPostEstimatedDeliveryDate *DateTime      `json:"easypost_estimated_delivery_date,omitempty"`
+	TimeInTransitPercentiles      *TimeInTransit `json:"days_in_transit,omitempty"`
+}
+
+// DeliveryDateForZipPairEstimate is a single zip-pair-based delivery date estimate for a carrier-service level combination.
+type DeliveryDateForZipPairEstimate struct {
+	Carrier                   string                               `json:"carrier,omitempty"`
+	Service                   string                               `json:"service,omitempty"`
+	EasyPostTimeInTransitData *TimeInTransitDetailsForDeliveryDate `json:"easypost_time_in_transit_data,omitempty"`
+}
+
+// EstimateDeliveryDateForZipPairResult is the result of the EstimateDeliveryDateForZipPair method, containing the estimated delivery date of each carrier-service level combination and additional metadata.
+type EstimateDeliveryDateForZipPairResult struct {
+	CarriersWithoutEstimates []string                          `json:"carriers_without_tint_estimates,omitempty"`
+	OriginPostalCode         string                            `json:"from_zip,omitempty"`
+	DestinationPostalCode    string                            `json:"to_zip,omitempty"`
+	SaturdayDelivery         bool                              `json:"saturday_delivery,omitempty"`
+	PlannedShipDate          *DateTime                         `json:"planned_ship_date,omitempty"`
+	Estimates                []*DeliveryDateForZipPairEstimate `json:"results,omitempty"`
+}
+
+// EstimateDeliveryDateForZipPairParams are used in the EstimateDeliveryDateForZipPair method.
+type EstimateDeliveryDateForZipPairParams struct {
+	OriginPostalCode      string   `json:"from_zip,omitempty"`
+	DestinationPostalCode string   `json:"to_zip,omitempty"`
+	Carriers              []string `json:"carriers,omitempty"`
+	PlannedShipDate       string   `json:"planned_ship_date,omitempty"`
+	SaturdayDelivery      bool     `json:"saturday_delivery,omitempty"`
+}
+
+// TimeInTransitDetailsForShipDate contains the time-in-transit details and estimated delivery date for a specific ShipDateForZipPairRecommendation or RecommendShipDateForShipmentResult.
+type TimeInTransitDetailsForShipDate struct {
+	DesiredDeliveryDate         *DateTime      `json:"desired_delivery_date,omitempty"`
+	EasyPostRecommendedShipDate *DateTime      `json:"ship_on_date,omitempty"`
+	DeliveryDateConfidence      float64        `json:"delivery_date_confidence,omitempty"`
+	EstimatedTransitDays        int            `json:"estimated_transit_days,omitempty"`
+	TimeInTransitPercentiles    *TimeInTransit `json:"days_in_transit,omitempty"`
+}
+
+// ShipDateForZipPairRecommendation is a single zip-pair-based ship date recommendation for a carrier-service level combination.
+type ShipDateForZipPairRecommendation struct {
+	Carrier                   string                           `json:"carrier,omitempty"`
+	Service                   string                           `json:"service,omitempty"`
+	EasyPostTimeInTransitData *TimeInTransitDetailsForShipDate `json:"easypost_time_in_transit_data,omitempty"`
+}
+
+// RecommendShipDateForZipPairResult is the result of the RecommendShipDateForZipPair method, containing the recommended ship date of each carrier-service level combination and additional metadata.
+type RecommendShipDateForZipPairResult struct {
+	CarriersWithoutEstimates []string                            `json:"carriers_without_tint_estimates,omitempty"`
+	OriginPostalCode         string                              `json:"from_zip,omitempty"`
+	DestinationPostalCode    string                              `json:"to_zip,omitempty"`
+	SaturdayDelivery         bool                                `json:"saturday_delivery,omitempty"`
+	DesiredDeliveryDate      *DateTime                           `json:"desired_delivery_date,omitempty"`
+	Estimates                []*ShipDateForZipPairRecommendation `json:"results,omitempty"`
+}
+
+// RecommendShipDateForZipPairParams are used in the RecommendShipDateForZipPair method.
+type RecommendShipDateForZipPairParams struct {
+	OriginPostalCode      string   `json:"from_zip,omitempty"`
+	DestinationPostalCode string   `json:"to_zip,omitempty"`
+	Carriers              []string `json:"carriers,omitempty"`
+	DesiredDeliveryDate   string   `json:"desired_delivery_date,omitempty"`
+	SaturdayDelivery      bool     `json:"saturday_delivery,omitempty"`
+}
+
+// EstimateDeliveryDateForZipPair retrieves the estimated delivery date of each carrier-service level combination via the Smart Deliver By API, based on a specific ship date and origin-destination postal code pair.
+func (c *Client) EstimateDeliveryDateForZipPair(params *EstimateDeliveryDateForZipPairParams) (out *EstimateDeliveryDateForZipPairResult, err error) {
+	return c.EstimateDeliveryDateForZipPairWithContext(context.Background(), params)
+}
+
+// EstimateDeliveryDateForZipPairWithContext performs the same operation as EstimateDeliveryDateForZipPair, but allows specifying a context that can interrupt the request.
+func (c *Client) EstimateDeliveryDateForZipPairWithContext(ctx context.Context, params *EstimateDeliveryDateForZipPairParams) (out *EstimateDeliveryDateForZipPairResult, err error) {
+	err = c.post(ctx, "smartrate/deliver_by", params, &out)
+	return
+}
+
+// RecommendShipDateForZipPair retrieves the recommended ship date of each carrier-service level combination via the Smart Deliver On API, based on a specific desired delivery date and origin-destination postal code pair.
+func (c *Client) RecommendShipDateForZipPair(params *RecommendShipDateForZipPairParams) (out *RecommendShipDateForZipPairResult, err error) {
+	return c.RecommendShipDateForZipPairWithContext(context.Background(), params)
+}
+
+// RecommendShipDateForZipPairWithContext performs the same operation as RecommendShipDateForZipPair, but allows specifying a context that can interrupt the request.
+func (c *Client) RecommendShipDateForZipPairWithContext(ctx context.Context, params *RecommendShipDateForZipPairParams) (out *RecommendShipDateForZipPairResult, err error) {
+	err = c.post(ctx, "smartrate/deliver_on", params, &out)
+	return
+}