flexops 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46267de883ed8970bdcfc87d77c86edcf9b33a5d1ffe0d312a10961ea43646fb
-  data.tar.gz: 9c828d5d8fbc74b2b3abee2640b1742de692a800e51fe60f3fd671b728564dc6
+  metadata.gz: ae38cf941276d4053203fda4a44fb9ab1adb873d24bba9ec1de7fc634be3e7e2
+  data.tar.gz: 43b602d72cbac545bff0391aa2dee8ea28f73bd7807a6042ec17731fe7943881
 SHA512:
-  metadata.gz: 439f0b3d74903968585f2d980e80d00798f9784903100851804949a7602c3bc163f0ce3600e5602ebfe6fca0e85d93b64f2bc5b5269abfebd9eb573535db20b5
-  data.tar.gz: eff6ea869f9cfd93dca01e4bc9bfd794a64fb36f51825743ae7f0bef5783e8698b08324b976048b0a360622d6d49de9c355083fac6072007266080e5461aa874
+  metadata.gz: '0959231eed12a9abd27bc7d370ab9576e32393a131248e231f2d7bebb622c74c29c21596f55036c1af8df73a277a3cbb8ee282c516aca90fc787839c76f102dc'
+  data.tar.gz: 42fa01ac062f0f54ed7632e403a0d3a5ed37e3e942e6f11a45797b047f7f343c3b0419d354e83af9be217d58d1877a322ee7fee7fa6c79e9749e069cfca0f7cf

data/README.md

@@ -40,23 +40,49 @@ rates = client.shipping.get_rates(
   package: {weight: 16, weightUnit: "oz"}
 )
 
-# Create a label with the cheapest rate
-cheapest = rates["rates"].min_by { |r| r["rate"].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)
@@ -128,18 +154,22 @@ curl -X POST https://gateway.flexops.io/api/shipping/rates \
     "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/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/shipping.rb

@@ -26,8 +26,11 @@ module FlexOps
         @http.post("/api/shipping/rates/fastest", body: request)
       end
 
-      def create_label(request)
-        @http.post("#{ws_path}/shipping/labels", body: request)
+      # Returns a raw preview or label; confirmation always belongs to the caller.
+      def create_label(request = {}, idempotency_key: nil, **fields)
+        request = request.merge(fields)
+        @http.post("#{ws_path}/shipping/labels", body: request,
+                   headers: idempotency_key.nil? ? {} : { "Idempotency-Key" => idempotency_key })
       end
 
       def cancel_label(label_id)

data/lib/flexops/version.rb

@@ -7,5 +7,5 @@
 # ***********************************************************************
 
 module FlexOps
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flexops
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - FlexOps, LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json