flexops 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99bb604e4e35131d7525633fbfad7103b380170556b47250599192256636eec1
-  data.tar.gz: b9fb3ccd224541332bd03fd9e8510937fbed4d093c6ab3443dfd41fee0565229
+  metadata.gz: 7266826af89b91d17327ba0dda3a7318081657cd7d63805be1c7a2665ffcc69c
+  data.tar.gz: ab7acc1c279b73e6c84dcf57513368d28f5b85386928260bc23b806226f2fd85
 SHA512:
-  metadata.gz: 12823e90e21cd1eeefcf883ab5c7ed9a4e9d008b2e26bd80ac6014a05e3b6e6b57e4054a3757574173886b2c8ed6a08e6c8d3a2863f6034eb592e6e8d03da5c1
-  data.tar.gz: fb7a48fb211dfb1af4ddd9a0be588eb58318b8ffd445578a09dcacdef625ff9dc8e3dbc593b59a21da18acf678d67d9ca0bd76aef55a22843be9748bfddcf5fa
+  metadata.gz: '08dcd0f4f95c49a14ef83017a81352a4d5f3e9144ec9724b2af6d86882154d1abf7efd54eb2a9dfaa5a8509871c6686f428b90dc13b8834ef605315ff00fc6bd'
+  data.tar.gz: 6a854d05d30916be65b30cca8d6c03873bf8f5174df48721c1193c6c54d8aa5cd742767d285b9fd3d8a96c37dff72ac0ca99213d533c926f5302b8d0eaf3bf95

data/README.md

@@ -29,8 +29,8 @@ require "flexops"
 
 # API key authentication (recommended for server-to-server)
 client = FlexOps::Client.new(
-  api_key: "fxk_live_...",
-  workspace_id: "ws_abc123"
+  api_key: "live_...",
+  workspace_id: "your-workspace-id"
 )
 
 # Get shipping rates from all carriers
@@ -90,7 +90,7 @@ separate contracts. The SDK never automatically confirms a preview.
 ### API key (recommended)
 
 ```ruby
-client = FlexOps::Client.new(api_key: "fxk_live_...", workspace_id: "ws_abc123")
+client = FlexOps::Client.new(api_key: "live_...", workspace_id: "your-workspace-id")
 ```
 
 ### Email / password
@@ -99,15 +99,15 @@ client = FlexOps::Client.new(api_key: "fxk_live_...", workspace_id: "ws_abc123")
 client = FlexOps::Client.new(base_url: "https://gateway.flexops.io")
 session = client.auth.login(email: "user@example.com", password: "password")
 client.set_access_token(session["data"]["token"])
-client.workspace_id = "ws_abc123"
+client.workspace_id = "your-workspace-id"
 ```
 
 ## Sandbox / test keys
 
-Use `fxk_test_...` (instead of `fxk_live_...`) to route to the sandbox environment. Mock carriers respond, nothing hits real carrier APIs, no charges, no real labels. Perfect for CI and integration tests.
+Use `test_...` (instead of `live_...`) to route to the sandbox environment. Mock carriers respond, nothing hits real carrier APIs, no charges, no real labels. Perfect for CI and integration tests.
 
 ```ruby
-client = FlexOps::Client.new(api_key: "fxk_test_...", workspace_id: "ws_abc123")
+client = FlexOps::Client.new(api_key: "test_...", workspace_id: "your-workspace-id")
 ```
 
 ## Carrier-specific calls
@@ -209,6 +209,34 @@ client.email_templates.upsert(eventType: 3, subjectTemplate: "Delivered: {{track
 client.email_templates.preview(subject_template: "Hi {{recipient_name}}", html_body_template: "<p>{{status}}</p>")
 ```
 
+## Multi-package labels
+
+One order shipped in several boxes with the same carrier and service; each box gets its own label and
+a box that fails does not stop the others. Multi-package labels cannot carry HAZMAT: send
+`FlexOps::HazmatClassification::NONE` or leave `hazmatClassification` out. `maximumPostageAmount` is required: the
+most the whole shipment may cost in USD (positive, at most two decimals). The Gateway refuses to buy a box that would
+take the total above it (`PriceCeilingExceeded`; once the amount is used up the remaining boxes report
+`PriceCeilingReached`), and a request without a valid ceiling is 400 `ApprovalRequired`.
+
+```ruby
+begin
+  shipment = client.shipping.create_multi_package(
+    { orderId: 12345, carrierCode: "USPS", serviceCode: "PRIORITY",
+      hazmatClassification: FlexOps::HazmatClassification::NONE,
+      maximumPostageAmount: 25.00, # required: the most the whole shipment may cost, in USD
+      packages: [{ weightInOunces: 16, lengthInInches: 10, widthInInches: 8, heightInInches: 4, packageReference: "Box 1 of 2" },
+                 { weightInOunces: 8, lengthInInches: 6, widthInInches: 6, heightInInches: 6, packageReference: "Box 2 of 2" }] },
+    idempotency_key: "order-12345-boxes" # optional; reuse it when you retry
+  )
+rescue FlexOps::Error => e
+  # No label was bought: 422 AllPackagesFailed, or 409 OutcomeUnknown when a label may exist
+  # (check the order before buying again). e.data holds the per-box results.
+end
+```
+
+`client.returns.get` reads a received return by its numeric return id; read an RMA with
+`client.returns.get_rma("RMA-1001")` or page through them with `client.returns.list_rmas`.
+
 ## Wallet balance
 
 ```ruby
@@ -287,7 +315,7 @@ 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/shipping/rates \
-  -H "X-API-Key: fxk_live_..." \
+  -H "X-API-Key: live_..." \
   -H "Content-Type: application/json" \
   -d '{
     "origin": {"addressLine1": "123 Main St", "city": "New York", "stateProvince": "NY", "postalCode": "10001", "countryCode": "US"},
@@ -298,7 +326,7 @@ curl -X POST https://gateway.flexops.io/api/shipping/rates \
 # Preview a live label; this does not purchase it.
 # hazmatClassification 0 = not hazardous; required when there is no orderId.
 curl -X POST https://gateway.flexops.io/api/shipping/labels \
-  -H "X-API-Key: fxk_live_..." \
+  -H "X-API-Key: live_..." \
   -H "Content-Type: application/json" \
   -d '{
     "carrierCode": "USPS", "serviceCode": "GROUND_ADVANTAGE",
@@ -315,14 +343,14 @@ curl -X POST https://gateway.flexops.io/api/shipping/labels \
 
 # Track a shipment
 curl https://gateway.flexops.io/api/shipping/track/9400111899223456789012 \
-  -H "X-API-Key: fxk_live_..."
+  -H "X-API-Key: live_..."
 
 # Cancel a label
 curl -X DELETE "https://gateway.flexops.io/api/shipping/labels/lbl_123?carrierCode=USPS" \
-  -H "X-API-Key: fxk_live_..."
+  -H "X-API-Key: live_..."
 ```
 
-Use an `fxk_test_...` key instead of `fxk_live_...` to hit the sandbox environment; mock carriers respond, no real charges, no real labels.
+Use a `test_...` key instead of `live_...` to hit the sandbox environment; mock carriers respond, no real charges, no real labels.
 
 ## Resources
 
@@ -330,12 +358,12 @@ Use an `fxk_test_...` key instead of `fxk_live_...` to hit the sandbox environme
 |----------|-------------|
 | `client.auth` | Login, token refresh, logout |
 | `client.workspaces` | List and read workspaces; list, invite and remove members, change roles |
-| `client.shipping` | Rate shopping, labels, tracking, address validation, batch, cancel |
+| `client.shipping` | Rate shopping, labels, multi-package labels, tracking, address validation, batch, cancel |
 | `client.carriers` | USPS, UPS, FedEx and DHL calls through the legacy proxy; writes are deprecated and need a user token |
 | `client.webhooks` | Subscription create/update/delete, secret rotation, test events, delivery logs, signature verification |
 | `client.wallet` | Workspace balance |
 | `client.insurance` | Providers, quotes, policies, void, claims |
-| `client.returns` | List and read returns; create RMAs, return labels, receive |
+| `client.returns` | List and read received returns; create, read and list RMAs; return labels; receive |
 | `client.analytics` | Shipments, orders, carrier performance (legacy proxy reads) |
 | `client.orders` | Order reads (legacy proxy) |
 | `client.inventory` | Inventory reads (legacy proxy) |
@@ -355,8 +383,8 @@ API keys, workspace settings and account management are managed in the FlexOps p
 ```ruby
 client = FlexOps::Client.new(
   base_url:     "https://gateway.flexops.io",  # API base URL
-  api_key:      "fxk_live_...",            # API key auth
-  workspace_id: "ws_abc123",               # Default workspace
+  api_key:      "live_...",                # API key auth
+  workspace_id: "your-workspace-id",       # Default workspace
   timeout:      30                         # Request timeout (seconds)
 )
 ```

data/lib/flexops/errors.rb

@@ -8,13 +8,16 @@
 
 module FlexOps
   class Error < StandardError
-    attr_reader :status, :code, :errors
+    # data is the envelope's "data" on an error reply, when the Gateway sends one. A
+    # multi-package 422 AllPackagesFailed or 409 OutcomeUnknown carries the per-box results there.
+    attr_reader :status, :code, :errors, :data
 
-    def initialize(message, status: 0, code: nil, errors: nil)
+    def initialize(message, status: 0, code: nil, errors: nil, data: nil)
       super(message)
       @status = status
       @code = code
       @errors = errors
+      @data = data
     end
   end
 

data/lib/flexops/http.rb

@@ -117,7 +117,8 @@ module FlexOps
           error_body["message"] || "HTTP #{status}: #{response.message}",
           status: status,
           code: error_body["errorCode"] || error_body["code"] || (status == 403 ? "FORBIDDEN" : nil),
-          errors: error_body["errors"]
+          errors: error_body["errors"],
+          data: error_body["data"]
         )
 
         raise error unless retryable?(method, status, error.code)

data/lib/flexops/resources/returns.rb

@@ -6,6 +6,8 @@
 # Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
 # ***********************************************************************
 
+require "erb"
+
 module FlexOps
   module Resources
     class Returns
@@ -14,15 +16,30 @@ module FlexOps
         @ws_id = ws_id_proc
       end
 
+      # Lists received returns (start_date and end_date are ISO 8601; the Gateway defaults to the
+      # last 30 days). To list return authorizations, use list_rmas.
       def list(page: nil, page_size: nil, start_date: nil, end_date: nil)
         query = { page: page, pageSize: page_size, startDate: start_date, endDate: end_date }.compact
         @http.get("#{ws_path}/returns", query: query.empty? ? nil : query)
       end
 
+      # Reads a received return by its numeric return id ("returnId" on a listed return or an RMA).
+      # An RMA number such as "RMA-1001" is not a return id and matches no Gateway route; use get_rma.
       def get(return_id)
         @http.get("#{ws_path}/returns/#{return_id}")
       end
 
+      # Lists return authorizations (RMAs), one page at a time.
+      def list_rmas(page: nil, page_size: nil)
+        query = { page: page, pageSize: page_size }.compact
+        @http.get("#{ws_path}/returns/rma", query: query.empty? ? nil : query)
+      end
+
+      # Reads a return authorization by its RMA number, for example "RMA-1001".
+      def get_rma(rma_number)
+        @http.get("#{ws_path}/returns/rma/#{ERB::Util.url_encode(rma_number.to_s)}")
+      end
+
       # Creates an RMA and returns the enveloped RMA (201).
       #
       # request:: { orderId: (a number), orderNumber: (optional), reason:,

data/lib/flexops/resources/shipping.rb

@@ -60,6 +60,37 @@ module FlexOps
         @http.post("/api/addresses/validate", body: to_validation_address(address))
       end
 
+      # Buys labels for one order shipped in 1 to 99 boxes with the same carrier and service
+      # (POST /api/shipping/multi-package, the Gateway MultiPackageShipmentRequest):
+      #
+      #   { orderId: 12345, carrierCode: "USPS", serviceCode: (optional), labelFormat: (optional),
+      #     shipDate: (optional), hazmatClassification: (optional), maximumPostageAmount: 25.00,
+      #     packages: [{ weightInOunces:, lengthInInches:, widthInInches:, heightInInches:,
+      #                  deliveryConfirmationRequired: (optional), signatureConfirmationRequired: (optional),
+      #                  insuranceCoverageRequested: (optional), insuredValue: (optional),
+      #                  packageReference: (optional) }] }
+      #
+      # maximumPostageAmount is required: the most the whole shipment may cost, in USD (positive, at most
+      # two decimals). The Gateway refuses to buy a box that would take the total above it, so you never
+      # pay more: a box priced above what is left reports PriceCeilingExceeded, and once the amount is
+      # used up the remaining boxes report PriceCeilingReached and are not bought. Boxes already bought
+      # stay bought. A missing or invalid value is 400 ApprovalRequired.
+      #
+      # Weight is in ounces and every dimension in inches; all four are required. Multi-package
+      # labels cannot carry HAZMAT yet: send HazmatClassification::NONE or leave hazmatClassification
+      # out (any other class is refused with 400 HazmatNotSupported).
+      #
+      # Returns the envelope when at least one label was bought (check data["failedPackages"] and
+      # each box in data["labels"]). When none was, the Gateway answers 422 AllPackagesFailed, or 409
+      # OutcomeUnknown when a box's carrier outcome is unknown and a label may exist: both raise
+      # FlexOps::Error whose data holds the per-box results. After OutcomeUnknown, check the order
+      # before buying again. Pass your own idempotency_key (and reuse it) to make a retry you run
+      # yourself safe.
+      def create_multi_package(request, idempotency_key: nil)
+        @http.post("/api/shipping/multi-package", body: request,
+                   headers: idempotency_key.nil? ? {} : { "Idempotency-Key" => idempotency_key })
+      end
+
       # The payload is sent as given. Set hazmatClassification on an item only when you have a declaration.
       def create_batch(request)
         @http.post("#{ws_path}/labels/batch", body: request)

data/lib/flexops/version.rb

@@ -7,5 +7,5 @@
 # ***********************************************************************
 
 module FlexOps
-  VERSION = "2.0.0"
+  VERSION = "2.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flexops
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - FlexOps, LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json