flexops 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13d2f7754ba0f328f7deba370389156b15fa40b8e5a23b36f6eab43b8ddf6129
-  data.tar.gz: 433300bc3d7dab3012f76b3e5450456a6a2fde313a31b032f8e5e21c61a2c0f1
+  metadata.gz: ae38cf941276d4053203fda4a44fb9ab1adb873d24bba9ec1de7fc634be3e7e2
+  data.tar.gz: 43b602d72cbac545bff0391aa2dee8ea28f73bd7807a6042ec17731fe7943881
 SHA512:
-  metadata.gz: ce112d64b50b36231df3d187a6b2a093b66707b1425c556284666b8eb272a7353f6c1111008bcaaf9a9fc6ad592ea952645c8da70ecce24eb1e442898c388092
-  data.tar.gz: c0409a3b240c0f18d2dba7993a682adf83281d3ef5c3223ded998b3f9c21a07a3f18ab32ec15337c08d42de377a5e2dd95cf488d8c730a7724bbb89382b607ec
+  metadata.gz: '0959231eed12a9abd27bc7d370ab9576e32393a131248e231f2d7bebb622c74c29c21596f55036c1af8df73a277a3cbb8ee282c516aca90fc787839c76f102dc'
+  data.tar.gz: 42fa01ac062f0f54ed7632e403a0d3a5ed37e3e942e6f11a45797b047f7f343c3b0419d354e83af9be217d58d1877a322ee7fee7fa6c79e9749e069cfca0f7cf

data/README.md

@@ -35,28 +35,54 @@ client = FlexOps::Client.new(
 
 # Get shipping rates from all carriers
 rates = client.shipping.get_rates(
-  from_address: {street1: "123 Main St", city: "New York", state: "NY", zip: "10001", country: "US"},
-  to_address:   {street1: "456 Oak Ave", city: "Los Angeles", state: "CA", zip: "90210", country: "US"},
-  parcel:       {weight: 16, weight_unit: "oz"}
+  origin: {addressLine1: "123 Main St", city: "New York", stateProvince: "NY", postalCode: "10001"},
+  destination: {addressLine1: "456 Oak Ave", city: "Los Angeles", stateProvince: "CA", postalCode: "90210"},
+  package: {weight: 16, weightUnit: "oz"}
 )
 
-# Create a label with the cheapest rate
-cheapest = rates["data"].min_by { |r| r["totalCost"].to_f }
-label = client.shipping.create_label(
-  carrier:      cheapest["carrier"],
-  service:      cheapest["service"],
-  from_address: {name: "Warehouse", street1: "123 Main St", city: "New York", state: "NY", zip: "10001", country: "US"},
-  to_address:   {name: "Customer",  street1: "456 Oak Ave", city: "Los Angeles", state: "CA", zip: "90210", country: "US"},
-  parcel:       {weight: 16, weight_unit: "oz"}
-)
-
-puts "Label URL: #{label["data"]["labelUrl"]}"
-puts "Tracking:  #{label["data"]["trackingNumber"]}"
+request = {
+  carrierCode: "USPS", serviceCode: "GROUND_ADVANTAGE",
+  origin: {name: "Warehouse", addressLine1: "123 Main St", city: "New York", stateProvince: "NY", postalCode: "10001", countryCode: "US"},
+  destination: {name: "Customer", addressLine1: "456 Oak Ave", city: "Los Angeles", stateProvince: "CA", postalCode: "90210", countryCode: "US"},
+  package: {weight: 16, weightUnit: "oz"},
+  maximumPostageAmount: 10.25 # Caller-approved ceiling in USD.
+}
+preview = client.shipping.create_label(request)
+puts preview["quotedPostageAmount"]
+
+# Call only after explicit caller approval, within five minutes.
+purchase_approved_label = lambda do |purchase_key|
+  client.shipping.create_label(
+    request.merge(confirmationToken: preview["confirmationToken"]),
+    idempotency_key: purchase_key # Persist per purchase; reuse on retries.
+  )
+end
 
 # Track a shipment
 info = client.shipping.track("9400111899223456789012")
 ```
 
+### Live label approval (1.1.0+)
+
+The example below requires SDK 1.1.0 or later. Version 1.0.2 does not
+include the per-call idempotency argument.
+
+For live domestic single-label requests, `maximumPostageAmount` is required: positive
+USD, at most two decimal places, up to 1,000,000. Missing or invalid values return
+400 `ApprovalRequired`. Omitting `confirmationToken` returns a raw 200 preview
+(`status`, `quotedPostageAmount`, `maximumPostageAmount`, `currency`, `expiresAt`,
+`confirmationToken`). After explicit approval, resubmit the same shipment and ceiling
+with the token and a unique per-purchase `Idempotency-Key` header. The token expires
+after five minutes. A successful purchase returns the raw 201 label, including
+`labelId`, `trackingNumber`, `carrierCode`, and `labelData`, without a `data` wrapper.
+
+Keep the same key and request across retries. An uncertain outcome needs reconciliation;
+do not start another purchase with a new key. An expired approval returns 409
+`ApprovalExpired`; obtain and explicitly approve a fresh preview when no purchase is
+unresolved. The ceiling bounds postage authorization, not later adjustments or separate
+fees. Sandbox execution bypasses approval; batch, return, and raw carrier routes have
+separate contracts. The SDK never automatically confirms a preview.
+
 ## Authentication
 
 ### API key (recommended)
@@ -119,27 +145,31 @@ Every SDK method is a thin wrapper around the FlexOps REST API. If you want to v
 
 ```bash
 # Shop rates across all connected carriers
-curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/rates \
+curl -X POST https://gateway.flexops.io/api/shipping/rates \
   -H "X-API-Key: fxk_live_..." \
   -H "Content-Type: application/json" \
   -d '{
-    "fromAddress": {"street1": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "country": "US"},
-    "toAddress":   {"street1": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip": "90210", "country": "US"},
-    "parcel":      {"weight": 16, "weightUnit": "oz"}
+    "origin": {"addressLine1": "123 Main St", "city": "New York", "stateProvince": "NY", "postalCode": "10001", "countryCode": "US"},
+    "destination": {"addressLine1": "456 Oak Ave", "city": "Los Angeles", "stateProvince": "CA", "postalCode": "90210", "countryCode": "US"},
+    "package": {"weight": 16, "weightUnit": "oz"}
   }'
 
-# Create a label
+# Preview a live label; this does not purchase it.
 curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/labels \
   -H "X-API-Key: fxk_live_..." \
   -H "Content-Type: application/json" \
   -d '{
-    "carrier":  "USPS",
-    "service":  "PRIORITY_MAIL",
-    "fromAddress": {"name": "Warehouse", "street1": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "country": "US"},
-    "toAddress":   {"name": "Customer",  "street1": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip": "90210", "country": "US"},
-    "parcel":   {"weight": 16, "weightUnit": "oz"}
+    "carrierCode": "USPS", "serviceCode": "GROUND_ADVANTAGE",
+    "origin": {"name": "Warehouse", "addressLine1": "123 Main St", "city": "New York", "stateProvince": "NY", "postalCode": "10001", "countryCode": "US"},
+    "destination": {"name": "Customer", "addressLine1": "456 Oak Ave", "city": "Los Angeles", "stateProvince": "CA", "postalCode": "90210", "countryCode": "US"},
+    "package": {"weight": 16, "weightUnit": "oz"},
+    "maximumPostageAmount": 10.25
   }'
 
+# After explicit approval, resend the same body with confirmationToken from
+# the preview and an Idempotency-Key header unique to this purchase.
+# See the SDK example above; retain that key for retries.
+
 # Track a shipment
 curl https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/track/9400111899223456789012 \
   -H "X-API-Key: fxk_live_..."

data/lib/flexops/errors.rb

@@ -1,35 +1,35 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-08
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-module FlexOps
-  class Error < StandardError
-    attr_reader :status, :code, :errors
-
-    def initialize(message, status: 0, code: nil, errors: nil)
-      super(message)
-      @status = status
-      @code = code
-      @errors = errors
-    end
-  end
-
-  class AuthError < Error
-    def initialize(message = "Authentication required. Check your access token or API key.")
-      super(message, status: 401, code: "UNAUTHORIZED")
-    end
-  end
-
-  class RateLimitError < Error
-    attr_reader :retry_after
-
-    def initialize(retry_after: 0)
-      super("Rate limited. Retry after #{retry_after}s", status: 429, code: "RATE_LIMITED")
-      @retry_after = retry_after
-    end
-  end
-end
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  class Error < StandardError
+    attr_reader :status, :code, :errors
+
+    def initialize(message, status: 0, code: nil, errors: nil)
+      super(message)
+      @status = status
+      @code = code
+      @errors = errors
+    end
+  end
+
+  class AuthError < Error
+    def initialize(message = "Authentication required. Check your access token or API key.")
+      super(message, status: 401, code: "UNAUTHORIZED")
+    end
+  end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(retry_after: 0)
+      super("Rate limited. Retry after #{retry_after}s", status: 429, code: "RATE_LIMITED")
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/flexops/http.rb

@@ -38,8 +38,8 @@ module FlexOps
       request(:get, path, query: query)
     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)
@@ -56,7 +56,7 @@ module FlexOps
 
     private
 
-    def request(method, path, body: nil, query: nil)
+    def request(method, path, body: nil, query: nil, headers: {})
       uri = build_uri(path, query)
       last_error = nil
 
@@ -66,6 +66,7 @@ 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|
@@ -97,6 +98,7 @@ module FlexOps
           error = Error.new(
             error_body["message"] || "HTTP #{status}: #{response.message}",
             status: status,
+            code: error_body["errorCode"] || error_body["code"],
             errors: error_body["errors"]
           )
 

data/lib/flexops/resources/analytics.rb

@@ -1,85 +1,85 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-08
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-module FlexOps
-  module Resources
-    class Analytics
-      BASE = "/api/ApiProxy/api/v4/Analytics"
-
-      def initialize(http)
-        @http = http
-      end
-
-      def shipments_trend(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/ShipmentsTrend", query: date_query(start_date, end_date))
-      end
-
-      def carrier_summary(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/CarrierSummary", query: date_query(start_date, end_date))
-      end
-
-      def top_destinations(start_date: nil, end_date: nil, limit: nil)
-        @http.get("#{BASE}/TopDestinations", query: date_query(start_date, end_date).merge(limit: limit).compact)
-      end
-
-      def inventory_metrics
-        @http.get("#{BASE}/InventoryMetrics")
-      end
-
-      def stock_by_warehouse
-        @http.get("#{BASE}/StockByWarehouse")
-      end
-
-      def order_metrics(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/OrderMetrics", query: date_query(start_date, end_date))
-      end
-
-      def order_trend(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/OrderTrend", query: date_query(start_date, end_date))
-      end
-
-      def top_selling_products(start_date: nil, end_date: nil, limit: nil)
-        @http.get("#{BASE}/TopSellingProducts", query: date_query(start_date, end_date).merge(limit: limit).compact)
-      end
-
-      def returns_metrics(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/ReturnsMetrics", query: date_query(start_date, end_date))
-      end
-
-      def returns_trend(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/ReturnsTrend", query: date_query(start_date, end_date))
-      end
-
-      def return_reasons(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/ReturnReasons", query: date_query(start_date, end_date))
-      end
-
-      def performance_metrics(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/PerformanceMetrics", query: date_query(start_date, end_date))
-      end
-
-      def carrier_performance(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/CarrierPerformance", query: date_query(start_date, end_date))
-      end
-
-      def shipping_cost_analytics(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/ShippingCostAnalytics", query: date_query(start_date, end_date))
-      end
-
-      def delivery_performance(start_date: nil, end_date: nil)
-        @http.get("#{BASE}/DeliveryPerformance", query: date_query(start_date, end_date))
-      end
-
-      private
-
-      def date_query(start_date, end_date)
-        { startDate: start_date, endDate: end_date }.compact
-      end
-    end
-  end
-end
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    class Analytics
+      BASE = "/api/ApiProxy/api/v4/Analytics"
+
+      def initialize(http)
+        @http = http
+      end
+
+      def shipments_trend(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ShipmentsTrend", query: date_query(start_date, end_date))
+      end
+
+      def carrier_summary(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/CarrierSummary", query: date_query(start_date, end_date))
+      end
+
+      def top_destinations(start_date: nil, end_date: nil, limit: nil)
+        @http.get("#{BASE}/TopDestinations", query: date_query(start_date, end_date).merge(limit: limit).compact)
+      end
+
+      def inventory_metrics
+        @http.get("#{BASE}/InventoryMetrics")
+      end
+
+      def stock_by_warehouse
+        @http.get("#{BASE}/StockByWarehouse")
+      end
+
+      def order_metrics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/OrderMetrics", query: date_query(start_date, end_date))
+      end
+
+      def order_trend(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/OrderTrend", query: date_query(start_date, end_date))
+      end
+
+      def top_selling_products(start_date: nil, end_date: nil, limit: nil)
+        @http.get("#{BASE}/TopSellingProducts", query: date_query(start_date, end_date).merge(limit: limit).compact)
+      end
+
+      def returns_metrics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ReturnsMetrics", query: date_query(start_date, end_date))
+      end
+
+      def returns_trend(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ReturnsTrend", query: date_query(start_date, end_date))
+      end
+
+      def return_reasons(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ReturnReasons", query: date_query(start_date, end_date))
+      end
+
+      def performance_metrics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/PerformanceMetrics", query: date_query(start_date, end_date))
+      end
+
+      def carrier_performance(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/CarrierPerformance", query: date_query(start_date, end_date))
+      end
+
+      def shipping_cost_analytics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ShippingCostAnalytics", query: date_query(start_date, end_date))
+      end
+
+      def delivery_performance(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/DeliveryPerformance", query: date_query(start_date, end_date))
+      end
+
+      private
+
+      def date_query(start_date, end_date)
+        { startDate: start_date, endDate: end_date }.compact
+      end
+    end
+  end
+end

data/lib/flexops/resources/api_keys.rb

@@ -1,40 +1,40 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-08
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-module FlexOps
-  module Resources
-    class ApiKeys
-      def initialize(http, ws_id_proc)
-        @http = http
-        @ws_id = ws_id_proc
-      end
-
-      def list
-        @http.get("#{ws_path}/api-keys")
-      end
-
-      def create(request)
-        @http.post("#{ws_path}/api-keys", body: request)
-      end
-
-      def revoke(key_id)
-        @http.delete("#{ws_path}/api-keys/#{key_id}")
-      end
-
-      def rotate(key_id)
-        @http.post("#{ws_path}/api-keys/#{key_id}/rotate")
-      end
-
-      private
-
-      def ws_path
-        "/api/workspaces/#{@ws_id.call}"
-      end
-    end
-  end
-end
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    class ApiKeys
+      def initialize(http, ws_id_proc)
+        @http = http
+        @ws_id = ws_id_proc
+      end
+
+      def list
+        @http.get("#{ws_path}/api-keys")
+      end
+
+      def create(request)
+        @http.post("#{ws_path}/api-keys", body: request)
+      end
+
+      def revoke(key_id)
+        @http.delete("#{ws_path}/api-keys/#{key_id}")
+      end
+
+      def rotate(key_id)
+        @http.post("#{ws_path}/api-keys/#{key_id}/rotate")
+      end
+
+      private
+
+      def ws_path
+        "/api/workspaces/#{@ws_id.call}"
+      end
+    end
+  end
+end

data/lib/flexops/resources/auth.rb

@@ -1,57 +1,57 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-08
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-module FlexOps
-  module Resources
-    class Auth
-      def initialize(http)
-        @http = http
-      end
-
-      def login(email:, password:)
-        @http.post("/api/Account/login", body: { email: email, password: password })
-      end
-
-      def register(request)
-        @http.post("/api/Account/register", body: request)
-      end
-
-      def refresh_token(refresh_token)
-        @http.post("/api/Account/refresh-token", body: { 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
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    class Auth
+      def initialize(http)
+        @http = http
+      end
+
+      def login(email:, password:)
+        @http.post("/api/Account/login", body: { email: email, password: password })
+      end
+
+      def register(request)
+        @http.post("/api/Account/register", body: request)
+      end
+
+      def refresh_token(refresh_token)
+        @http.post("/api/Account/refresh-token", body: { 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