flexops 1.0.2 → 2.0.0

data/lib/flexops/http.rb

@@ -9,13 +9,24 @@
 require "net/http"
 require "uri"
 require "json"
+require "securerandom"
 
 module FlexOps
   class HttpClient
     DEFAULT_BASE_URL = "https://gateway.flexops.io"
     DEFAULT_TIMEOUT = 30
     MAX_RETRIES = 3
+    # Statuses a GET is retried on.
     RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    # Statuses where a keyed write either never ran or is replayed by the Gateway. Never 500:
+    # the Gateway does not cache a 5xx response, so a retry would run the write again.
+    WRITE_RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+    WRITE_METHODS = %i[post put patch].freeze
+    IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+    # The Gateway's 409 while the first request with the same Idempotency-Key is still running.
+    IDEMPOTENCY_CONFLICT = "IDEMPOTENCY_CONFLICT"
+
+    attr_reader :access_token
 
     def initialize(base_url: DEFAULT_BASE_URL, api_key: nil, access_token: nil, timeout: DEFAULT_TIMEOUT)
       @base_url = base_url.chomp("/")
@@ -34,30 +45,33 @@ module FlexOps
       @access_token = nil
     end
 
-    def get(path, query: nil)
-      request(:get, path, query: query)
+    def get(path, query: nil, headers: {})
+      request(:get, path, query: query, headers: headers)
     end
 
-    def post(path, body: nil, query: nil)
-      request(:post, path, body: body, query: query)
+    def post(path, body: nil, query: nil, headers: {})
+      request(:post, path, body: body, query: query, headers: headers)
     end
 
-    def put(path, body: nil)
-      request(:put, path, body: body)
+    def put(path, body: nil, headers: {})
+      request(:put, path, body: body, headers: headers)
     end
 
-    def patch(path, body: nil)
-      request(:patch, path, body: body)
+    def patch(path, body: nil, headers: {})
+      request(:patch, path, body: body, headers: headers)
     end
 
-    def delete(path)
-      request(:delete, path)
+    def delete(path, headers: {})
+      request(:delete, path, headers: headers)
     end
 
     private
 
-    def request(method, path, body: nil, query: nil)
+    def request(method, path, body: nil, query: nil, headers: {})
       uri = build_uri(path, query)
+      # Every write carries one key for all of its attempts, so the Gateway replays a write it
+      # already finished instead of running it (and charging the wallet) again.
+      headers = with_idempotency_key(method, headers)
       last_error = nil
 
       (0..MAX_RETRIES).each do |attempt|
@@ -66,57 +80,71 @@ module FlexOps
         end
 
         req = build_request(method, uri, body)
+        headers.each { |name, value| req[name] = value }
         begin
           response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
                                      open_timeout: @timeout, read_timeout: @timeout) do |http|
             http.request(req)
           end
+        rescue StandardError => e
+          # The Gateway may have run a timed-out or dropped request. GETs and keyed writes are
+          # safe to send again; a DELETE is not covered by the idempotency middleware.
+          raise if method == :delete
 
-          status = response.code.to_i
+          last_error = e
+          next
+        end
 
-          if status >= 200 && status < 300
-            return parse_response(response)
-          end
+        status = response.code.to_i
 
-          if status == 401
-            raise AuthError
-          end
+        if status >= 200 && status < 300
+          return parse_response(response)
+        end
 
-          if status == 403
-            raise Error.new("Access denied. Check your plan tier and feature entitlements.", status: 403, code: "FORBIDDEN")
-          end
+        if status == 401
+          raise AuthError
+        end
 
-          if status == 429
-            retry_after = (response["retry-after"] || "0").to_i
-            last_error = RateLimitError.new(retry_after: retry_after)
-            next if RETRYABLE_STATUSES.include?(429)
-            raise last_error
-          end
+        # Rate limited: the request was refused before it ran, so every method retries.
+        if status == 429
+          retry_after = (response["retry-after"] || "0").to_i
+          last_error = RateLimitError.new(retry_after: retry_after)
+          next
+        end
 
-          error_body = parse_error_body(response)
-          error = Error.new(
-            error_body["message"] || "HTTP #{status}: #{response.message}",
-            status: status,
-            errors: error_body["errors"]
-          )
+        error_body = parse_error_body(response)
+        error = Error.new(
+          error_body["message"] || "HTTP #{status}: #{response.message}",
+          status: status,
+          code: error_body["errorCode"] || error_body["code"] || (status == 403 ? "FORBIDDEN" : nil),
+          errors: error_body["errors"]
+        )
 
-          if RETRYABLE_STATUSES.include?(status)
-            last_error = error
-            next
-          end
+        raise error unless retryable?(method, status, error.code)
 
-          raise error
-        rescue Error
-          raise
-        rescue StandardError => e
-          last_error = e
-          next if attempt < MAX_RETRIES
-        end
+        last_error = error
       end
 
       raise last_error || Error.new("Request failed after retries", code: "RETRY_EXHAUSTED")
     end
 
+    # GETs retry on every RETRYABLE_STATUSES status. A write retries only where the Gateway either
+    # did not run it or will replay it for the same Idempotency-Key. A DELETE retries only on 429.
+    def retryable?(method, status, code)
+      case method
+      when :get then RETRYABLE_STATUSES.include?(status)
+      when :delete then false
+      else status == 409 ? code == IDEMPOTENCY_CONFLICT : WRITE_RETRYABLE_STATUSES.include?(status)
+      end
+    end
+
+    def with_idempotency_key(method, headers)
+      return headers unless WRITE_METHODS.include?(method)
+
+      given = headers.any? { |name, value| name.to_s.casecmp?(IDEMPOTENCY_KEY_HEADER) && !value.to_s.empty? }
+      given ? headers : headers.merge(IDEMPOTENCY_KEY_HEADER => SecureRandom.uuid)
+    end
+
     def build_uri(path, query)
       url = "#{@base_url}#{path.start_with?("/") ? path : "/#{path}"}"
       uri = URI.parse(url)
@@ -150,7 +178,11 @@ module FlexOps
       req
     end
 
+    # A 2xx with no body (204, or Content-Length 0) returns nil; JSON is parsed; anything else,
+    # such as a label file, is returned as the raw body string.
     def parse_response(response)
+      return nil if response.code.to_i == 204 || response["content-length"] == "0" || response.body.nil? || response.body.empty?
+
       content_type = response["content-type"] || ""
       if content_type.include?("application/json")
         JSON.parse(response.body)
@@ -160,7 +192,8 @@ module FlexOps
     end
 
     def parse_error_body(response)
-      JSON.parse(response.body)
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Hash) ? parsed : {}
     rescue StandardError
       {}
     end

data/lib/flexops/resources/auth.rb

@@ -8,6 +8,8 @@
 
 module FlexOps
   module Resources
+    # Token acquisition for operations that need a signed-in user. Account management
+    # (registration, profile, passwords) belongs to the FlexOps portals.
     class Auth
       def initialize(http)
         @http = http
@@ -17,41 +19,18 @@ module FlexOps
         @http.post("/api/Account/login", body: { email: email, password: password })
       end
 
-      def register(request)
-        @http.post("/api/Account/register", body: request)
-      end
+      # The Gateway RefreshTokenRequest requires the expired access token as well as the refresh
+      # token; it defaults to the client's current access token.
+      def refresh_token(refresh_token, access_token: nil)
+        token = access_token || @http.access_token
+        raise ArgumentError, "access_token is required to refresh a session" if token.to_s.empty?
 
-      def refresh_token(refresh_token)
-        @http.post("/api/Account/refresh-token", body: { refreshToken: refresh_token })
+        @http.post("/api/Account/refresh-token", body: { token: token, refreshToken: refresh_token })
       end
 
       def logout
         @http.post("/api/Account/logout")
       end
-
-      def get_profile
-        @http.get("/api/Account/profile")
-      end
-
-      def update_profile(data)
-        @http.put("/api/Account/profile", body: data)
-      end
-
-      def change_password(current_password:, new_password:)
-        @http.post("/api/Account/change-password", body: { currentPassword: current_password, newPassword: new_password })
-      end
-
-      def forgot_password(email:)
-        @http.post("/api/Account/forgot-password", body: { email: email })
-      end
-
-      def reset_password(token:, new_password:)
-        @http.post("/api/Account/reset-password", body: { token: token, newPassword: new_password })
-      end
-
-      def verify_email(token:)
-        @http.post("/api/Account/verify-email", body: { token: token })
-      end
     end
   end
 end

data/lib/flexops/resources/carbon_offsets.rb

@@ -0,0 +1,60 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-10-19
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    # Carbon offsets for shipments. Answers use the { success, data, message, errorCode } envelope.
+    class CarbonOffsets
+      def initialize(http, ws_id_proc)
+        @http = http
+        @ws_id = ws_id_proc
+      end
+
+      def quote(weight_lbs:, distance_miles:)
+        @http.post("#{ws_path}/quote", body: { weightLbs: weight_lbs, distanceMiles: distance_miles })
+      end
+
+      # Buys an offset for a shipment and debits the workspace wallet.
+      # Pass an idempotency_key you store with the purchase to make your own retry safe: after an
+      # error or a timeout, retry with the same key and the Gateway returns the first result instead
+      # of buying again. Without one, the SDK's own retries still share a key, but a new call gets a new key.
+      def purchase(tracking_number:, weight_lbs:, distance_miles:, idempotency_key: nil)
+        @http.post("#{ws_path}/purchase",
+                   body: { trackingNumber: tracking_number, weightLbs: weight_lbs, distanceMiles: distance_miles },
+                   headers: idempotency_key.nil? ? {} : { "Idempotency-Key" => idempotency_key })
+      end
+
+      def list(page: nil, page_size: nil)
+        query = { page: page, pageSize: page_size }.compact
+        @http.get(ws_path, query: query.empty? ? nil : query)
+      end
+
+      def get(offset_id)
+        @http.get("#{ws_path}/#{offset_id}")
+      end
+
+      def summary
+        @http.get("#{ws_path}/summary")
+      end
+
+      def get_settings
+        @http.get("#{ws_path}/settings")
+      end
+
+      def update_settings(auto_offset_enabled:)
+        @http.put("#{ws_path}/settings", body: { autoOffsetEnabled: auto_offset_enabled })
+      end
+
+      private
+
+      def ws_path
+        "/api/workspaces/#{@ws_id.call}/carbon-offsets"
+      end
+    end
+  end
+end

data/lib/flexops/resources/carriers.rb

@@ -8,6 +8,11 @@
 
 module FlexOps
   module Resources
+    # Carrier-specific calls through the legacy /api/ApiProxy passthrough (sunset 2027-06-30).
+    # Lookups (GET) work with an API key or a user token. The writes (POST/PUT/DELETE) are
+    # deprecated and need a user token (auth.login): the Gateway refuses API-key writes on the
+    # proxy with 403 API_KEY_SCOPE_REQUIRED. Label generation through the proxy is closed (410 Gone);
+    # buy, cancel and schedule through client.shipping, client.pickups and client.scan_forms.
     class Carriers
       attr_reader :usps, :ups, :fedex, :dhl
 
@@ -30,20 +35,37 @@ module FlexOps
       def validate_address(params) = @http.get("#{PROXY}/api/v3/AddressValidation/getUspsValidateAndCorrectAddress", query: params)
       def city_state_lookup(zip_code) = @http.get("#{PROXY}/api/v3/AddressValidation/getUspsCityStateLookupByZipCode", query: { zipCode: zip_code })
       def zip_code_lookup(params) = @http.get("#{PROXY}/api/v3/AddressValidation/getUspsZipCodeLookupByAddress", query: params)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_domestic_rates(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postUspsSearchDomesticBaseRates", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_domestic_products(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postUspsSearchEligibleDomesticProducts", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_domestic_prices(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postUspsSearchEligibleDomesticPrices", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_international_rates(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postUspsSearchInternationalBaseRates", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_international_prices(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postUspsSearchEligibleInternationalPrices", body: body)
-      def create_domestic_label(body) = @http.post("#{PROXY}/api/v3/Shipping/postUspsGenerateDomesticShippingLabel", body: body)
-      def create_return_label(body) = @http.post("#{PROXY}/api/v3/Shipping/postUspsGenerateDomesticReturnsShippingLabel", body: body)
-      def create_international_label(body) = @http.post("#{PROXY}/api/v3/Shipping/postUspsGenerateInternationalShippingLabel", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_domestic_label = @http.delete("#{PROXY}/api/v3/Shipping/cancelUspsDomesticShipmentLabel")
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_international_label = @http.delete("#{PROXY}/api/v3/Shipping/cancelUspsInternationalShipmentLabel")
       def track_summary(params) = @http.get("#{PROXY}/api/v3/Tracking/getUspsTrackingSummaryInformation", query: params)
       def track_detail(params) = @http.get("#{PROXY}/api/v3/Tracking/getUspsTrackingDetailInformation", query: params)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_pickup(body) = @http.post("#{PROXY}/api/v3/CarrierPickup/postUspsCreateCarrierPickupSchedule", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_pickup = @http.delete("#{PROXY}/api/v3/CarrierPickup/cancelUspsCarrierPickupSchedule")
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_scan_form(body) = @http.post("#{PROXY}/api/v3/ScanForm/postUspsCreateScanFormLabelShipment", body: body)
       def delivery_standards(params) = @http.get("#{PROXY}/api/v3/ServiceStandards/getUspsGetDeliveryStandardsEstimates", query: params)
       def find_drop_off_locations(params) = @http.get("#{PROXY}/api/v3/LocationSearch/getUspsFindValidDropOffLocations", query: params)
@@ -57,17 +79,36 @@ module FlexOps
         @http = http
       end
 
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def validate_address(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsVerifyAddress", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_rates(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsRateCheck", body: body)
-      def create_label(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/generateNewUpsShipLabel", body: body)
       def track(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getSingleUpsTrackingDetail", query: params)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_pickup(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsCreatePickup", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_pickup = @http.delete("#{PROXY}/api/v2/ShippingLabel/deleteUpsPickup")
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_transit_times(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsGetTransitTimes", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_landed_cost(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsGetLandedCostQuote", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def search_locations(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsSearchLocations", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def upload_document(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsUploadPaperlessDocument", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_freight_shipment(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsCreateFreightShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_freight_rate(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postUpsGetFreightRate", body: body)
     end
 
@@ -78,26 +119,62 @@ module FlexOps
         @http = http
       end
 
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def validate_address(body) = @http.post("#{PROXY}/api/v3/AddressValidation/postFedExValidateAndCorrectDomesticAddress", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def validate_postal_code(body) = @http.post("#{PROXY}/api/v3/AddressValidation/postFedExValidatePostalCode", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_rates(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postRetrieveFedExRateAndTransitTimesAsync", body: body)
-      def create_shipment(body) = @http.post("#{PROXY}/api/v3/Shipping/postFedExCreateNewShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_shipment(body) = @http.put("#{PROXY}/api/v3/Shipping/putFedExCancelShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def validate_shipment(body) = @http.post("#{PROXY}/api/v3/Shipping/postFedExValidateShipment", body: body)
-      def create_return_shipment(body) = @http.post("#{PROXY}/api/v3/Shipping/postFedExCreateNewReturnShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def track(body) = @http.post("#{PROXY}/api/v3/Tracking/postFedExRetrieveTrackingInfoByTrackingNumber", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def track_multi_piece(body) = @http.post("#{PROXY}/api/v3/Tracking/postFedExRetrieveTrackingInfoForMultiPieceShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def register_tracking_notification(body) = @http.post("#{PROXY}/api/v3/Tracking/postFedExRegisterForTrackingNotification", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_pickup(body) = @http.post("#{PROXY}/api/v3/CarrierPickup/postFedExCreateCarrierPickupRequest", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_pickup(body) = @http.put("#{PROXY}/api/v3/CarrierPickup/putFedExCancelCarrierPickupRequest", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def search_locations(body) = @http.post("#{PROXY}/api/v3/LocationSearch/postFedExSearchValidLocations", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_service_standards(body) = @http.post("#{PROXY}/api/v3/ServiceStandards/postFedExRetrieveServicesAndTransitTimes", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_freight_rate(body) = @http.post("#{PROXY}/api/v3/Freight/postFedExGetFreightRateQuote", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_freight_shipment(body) = @http.post("#{PROXY}/api/v3/Freight/postFedExCreateFreightShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def ground_close(body) = @http.post("#{PROXY}/api/v3/GroundClose/postFedExCloseWithDocuments", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def upload_trade_documents(body) = @http.post("#{PROXY}/api/v3/Trade/postFedExUploadTradeDocuments", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_open_shipment(body) = @http.post("#{PROXY}/api/v3/OpenShip/postFedExCreateOpenShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def add_packages_to_open_shipment(body) = @http.post("#{PROXY}/api/v3/OpenShip/postFedExAddPackagesToOpenShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def confirm_open_shipment(body) = @http.post("#{PROXY}/api/v3/OpenShip/postFedExConfirmOpenShipment", body: body)
     end
 
@@ -110,16 +187,26 @@ module FlexOps
 
       def validate_address(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlValidateAddress", query: params)
       def get_rates(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlRates", query: params)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def get_multi_piece_rates(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postDhlMultiPieceRates", body: body)
       def get_products(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlProducts", query: params)
-      def create_shipment(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postDhlCreateShipment", body: body)
       def track(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlTrackSingleShipment", query: params)
       def track_multiple(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlTrackMultipleShipments", query: params)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def create_pickup(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postDhlCreatePickup", body: body)
-      def update_pickup(body) = @http.patch("#{PROXY}/api/v2/ShippingLabel/patchDhlUpdatePickup", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def cancel_pickup = @http.delete("#{PROXY}/api/v2/ShippingLabel/deleteDhlPickup")
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def calculate_landed_cost(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postDhlCalculateLandedCost", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def screen_shipment(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postDhlScreenShipment", body: body)
+      # @deprecated Legacy carrier proxy (sunset 2027-06-30). Needs a user token: API keys get 403
+      #   API_KEY_SCOPE_REQUIRED. Use client.shipping / client.pickups / client.scan_forms where they cover this.
       def upload_invoice(body) = @http.post("#{PROXY}/api/v2/ShippingLabel/postDhlUploadInvoice", body: body)
       def get_proof_of_delivery(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlElectronicProofOfDelivery", query: params)
       def get_reference_data(params) = @http.get("#{PROXY}/api/v2/ShippingLabel/getDhlReferenceData", query: params)

data/lib/flexops/resources/email_templates.rb

@@ -1,15 +1,22 @@
 # ***********************************************************************
 # Package          : flexops
 # Author           : FlexOps, LLC
-# Created          : 2026-03-31
+# Created          : 2026-10-19
 #
 # Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
 # ***********************************************************************
 
-# frozen_string_literal: true
-
 module FlexOps
   module Resources
+    # Branded tracking email templates, one per tracking event. Answers are bare JSON (no
+    # envelope); ids are GUID strings.
+    #
+    # Reads work with any API key or a user token. Writes (upsert, delete, preview) need a user
+    # token (auth.login) or an API key granted the opt-in "email-templates:write" scope; a key
+    # without it gets 403 API_KEY_SCOPE_REQUIRED.
+    #
+    # +eventType+ is the Gateway TrackingEmailEvent number: LabelCreated 0, InTransit 1,
+    # OutForDelivery 2, Delivered 3, Exception 4, ReturnToSender 5.
     class EmailTemplates
       def initialize(http, ws_id_proc)
         @http = http
@@ -17,33 +24,36 @@ module FlexOps
       end
 
       def list
-        @http.get("#{ws_path}/shipment-email-templates/")
-      end
-
-      def get(id)
-        @http.get("#{ws_path}/shipment-email-templates/#{id}")
+        @http.get(ws_path)
       end
 
-      def create(request)
-        @http.post("#{ws_path}/shipment-email-templates/", body: request)
+      def get(template_id)
+        @http.get("#{ws_path}/#{template_id}")
       end
 
-      def update(id, request)
-        @http.put("#{ws_path}/shipment-email-templates/#{id}", body: request)
+      # Creates or replaces the template for request's +eventType+.
+      #
+      # request:: { eventType: (0-5), subjectTemplate: (<= 500 chars), htmlBodyTemplate:,
+      #           isEnabled: (default true) }. Returns the template.
+      def upsert(request)
+        @http.put(ws_path, body: request)
       end
 
-      def delete(id)
-        @http.delete("#{ws_path}/shipment-email-templates/#{id}")
+      # Returns nil (204).
+      def delete(template_id)
+        @http.delete("#{ws_path}/#{template_id}")
       end
 
-      def preview(id, context = {})
-        @http.post("#{ws_path}/shipment-email-templates/#{id}/preview", body: context)
+      # Renders a draft with sample placeholder values. Returns { renderedSubject, renderedHtmlBody }.
+      def preview(subject_template:, html_body_template:)
+        @http.post("#{ws_path}/preview",
+                   body: { subjectTemplate: subject_template, htmlBodyTemplate: html_body_template })
       end
 
       private
 
       def ws_path
-        "/api/workspaces/#{@ws_id.call}"
+        "/api/workspaces/#{@ws_id.call}/email-templates"
       end
     end
   end

data/lib/flexops/resources/hs_codes.rb

@@ -8,31 +8,30 @@
 
 # frozen_string_literal: true
 
+require "erb"
+
 module FlexOps
   module Resources
+    # HS code lookup and landed cost. These routes are not workspace-scoped; each returns a bare
+    # (not enveloped) answer.
     class HsCodes
-      def initialize(http, ws_id_proc)
+      def initialize(http)
         @http = http
-        @ws_id = ws_id_proc
       end
 
       def search(query, destination_country: nil, max_results: 10)
         params = { query: query, destinationCountry: destination_country, maxResults: max_results }.compact
-        @http.get("#{ws_path}/shipping/hs-codes/search", query: params)
+        @http.get("/api/shipping/hs-codes/search", query: params)
       end
 
       def lookup(code)
-        @http.get("#{ws_path}/shipping/hs-codes/#{code}")
+        @http.get("/api/shipping/hs-codes/#{ERB::Util.url_encode(code.to_s)}")
       end
 
+      # request:: { destinationCountry:, items: [{ description:, quantity:, value:, weightOz:,
+      #           hsCode: (optional), originCountry:, skuOrProductId: (optional) }], shippingCost: }
       def estimate_landed_cost(request)
-        @http.post("#{ws_path}/shipping/landed-cost", body: request)
-      end
-
-      private
-
-      def ws_path
-        "/api/workspaces/#{@ws_id.call}"
+        @http.post("/api/shipping/landed-cost", body: request)
       end
     end
   end