flexops 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7266826af89b91d17327ba0dda3a7318081657cd7d63805be1c7a2665ffcc69c
-  data.tar.gz: ab7acc1c279b73e6c84dcf57513368d28f5b85386928260bc23b806226f2fd85
+  metadata.gz: 65a0d6f9908c2d73479d5a3b2987667357ffadb0849abd7091f2c56aa37ce3be
+  data.tar.gz: f1fcc33bd4e7dd7d1c46a181c04256f1a080aba0f9aaca008e2180d77872a05a
 SHA512:
-  metadata.gz: '08dcd0f4f95c49a14ef83017a81352a4d5f3e9144ec9724b2af6d86882154d1abf7efd54eb2a9dfaa5a8509871c6686f428b90dc13b8834ef605315ff00fc6bd'
-  data.tar.gz: 6a854d05d30916be65b30cca8d6c03873bf8f5174df48721c1193c6c54d8aa5cd742767d285b9fd3d8a96c37dff72ac0ca99213d533c926f5302b8d0eaf3bf95
+  metadata.gz: 789eeda78864db092ec75eba25d613c43dc2e9914976ed030784df0f854ccd3fa07d0c3fd7f028c51d5acb7a3b2c1a618a5d27a4b249557d5313251203a67045
+  data.tar.gz: 5f1b2001938eb3d2ed9fe3b5ad97eaca4b558a5e74fca674740c3d3c993003f8cfb90296723f7b4a58677e33d7bc92c55e2ffe25958780789b40a8aebfdcc932

data/README.md

@@ -82,7 +82,7 @@ Keep the same key and request across retries. An uncertain outcome needs reconci
 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
+fees. Sandbox keys follow the same approval and buy no postage; batch, return, and raw carrier routes have
 separate contracts. The SDK never automatically confirms a preview.
 
 ## Authentication
@@ -115,8 +115,11 @@ client = FlexOps::Client.new(api_key: "test_...", workspace_id: "your-workspace-
 `client.carriers.usps`, `.ups`, `.fedex` and `.dhl` call carrier routes through the legacy
 `/api/ApiProxy` passthrough, which the Gateway retires on 2027-06-30.
 
-- Lookups (GET), such as address checks, tracking and DHL rates, work with an API key or a user
-  token.
+- Lookups (GET), such as address checks, tracking and DHL rates, work with a user token, or an API
+  key that has the permission for the data: `shipping:read` for address, ZIP, city, location,
+  service point and reference lookups; `tracking:read` for tracking and proof of delivery;
+  `rates:read` for delivery standards, rates and products. Without it the Gateway returns 403
+  `API_KEY_SCOPE_REQUIRED`.
 - The writes (POST, PUT and DELETE, such as `usps.get_domestic_rates`, `fedex.cancel_shipment`
   or `ups.create_pickup`) are deprecated. They need a user token from `auth.login`: API keys get
   403 `API_KEY_SCOPE_REQUIRED`, and no API-key scope will be added for them. They stop working when
@@ -248,7 +251,14 @@ transaction history are managed in the FlexOps portal.
 
 ## Webhook subscriptions
 
+Managing webhooks needs a signed-in user's access token. The Gateway refuses API keys on every webhook route, reads included (`list` and `list_delivery_logs` as well as `create`, `update`, `delete`, `rotate_secret` and `test`), with 403 `SIGNED_IN_USER_REQUIRED`, whatever the key's scopes; the SDK raises `FlexOps::Error` with that `code`. Reads are refused too because webhook delivery logs carry each delivery's payload (order and customer data). A client with an API key sends the key even when an access token is also set, so use a client created without `api_key`. Verifying deliveries (below) makes no request and needs no credentials.
+
 ```ruby
+# Sign in as a user (or pass access_token:); an API key gets 403 SIGNED_IN_USER_REQUIRED here.
+client = FlexOps::Client.new(workspace_id: "your-workspace-id")
+session = client.auth.login(email: "user@example.com", password: "password")
+client.set_access_token(session["data"]["token"])
+
 # Leave events out to receive every event.
 webhook = client.webhooks.create(
   url: "https://your-app.com/webhooks/flexops",
@@ -364,9 +374,9 @@ Use a `test_...` key instead of `live_...` to hit the sandbox environment; mock
 | `client.wallet` | Workspace balance |
 | `client.insurance` | Providers, quotes, policies, void, claims |
 | `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) |
+| `client.analytics` | Shipments, orders, carrier performance (legacy proxy reads; API keys need each method's read permission) |
+| `client.orders` | Order reads (legacy proxy; API keys need `orders:read`) |
+| `client.inventory` | Inventory reads (legacy proxy; API keys need `inventory:read`) |
 | `client.pickups` | Schedule, list, read and cancel carrier pickups |
 | `client.scan_forms` | USPS scan forms |
 | `client.rules` | Shipping rules: create, read, update, delete, reorder, test |
@@ -376,6 +386,12 @@ Use a `test_...` key instead of `live_...` to hit the sandbox environment; mock
 | `client.report_schedules` | Scheduled report emails: create, update, toggle, delete |
 | `client.email_templates` | Tracking email templates: upsert, preview, delete |
 
+`client.analytics`, `client.orders` and `client.inventory` read through the legacy proxy. With an
+API key they need the permission for the data they read: `orders:read` for orders,
+`inventory:read` for inventory, and for analytics the permission named on each method
+(`shipping:read`, `inventory:read`, `orders:read` or `returns:read`). A key without it gets 403
+`API_KEY_SCOPE_REQUIRED`. Keys created with the default permissions have all of these.
+
 API keys, workspace settings and account management are managed in the FlexOps portals.
 
 ## Configuration

data/lib/flexops/http.rb

@@ -61,8 +61,8 @@ module FlexOps
       request(:patch, path, body: body, headers: headers)
     end
 
-    def delete(path, headers: {})
-      request(:delete, path, headers: headers)
+    def delete(path, query: nil, headers: {})
+      request(:delete, path, query: query, headers: headers)
     end
 
     private

data/lib/flexops/resources/analytics.rb

@@ -8,6 +8,12 @@
 
 module FlexOps
   module Resources
+    # Analytics through the legacy /api/ApiProxy passthrough (/api/ApiProxy/api/v4/Analytics/...).
+    # With an API key, each method requires the permission for the data it reads, named on the
+    # method: shipping:read for shipment, carrier and delivery metrics, inventory:read for
+    # inventory metrics, orders:read for order metrics and returns:read for returns metrics. A
+    # key without it gets 403 API_KEY_SCOPE_REQUIRED. Keys created with the default permissions
+    # have all four.
     class Analytics
       BASE = "/api/ApiProxy/api/v4/Analytics"
 
@@ -15,62 +21,77 @@ module FlexOps
         @http = http
       end
 
+      # Shipments trend over time. With an API key, requires shipping:read.
       def shipments_trend(start_date: nil, end_date: nil)
         @http.get("#{BASE}/ShipmentsTrend", query: date_query(start_date, end_date))
       end
 
+      # Carrier usage summary. With an API key, requires shipping:read.
       def carrier_summary(start_date: nil, end_date: nil)
         @http.get("#{BASE}/CarrierSummary", query: date_query(start_date, end_date))
       end
 
+      # Top shipping destinations. With an API key, requires shipping:read.
       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
 
+      # Inventory metrics (stock levels, low-stock alerts). With an API key, requires inventory:read.
       def inventory_metrics
         @http.get("#{BASE}/InventoryMetrics")
       end
 
+      # Stock levels by warehouse. With an API key, requires inventory:read.
       def stock_by_warehouse
         @http.get("#{BASE}/StockByWarehouse")
       end
 
+      # Order metrics (volume, revenue). With an API key, requires orders:read.
       def order_metrics(start_date: nil, end_date: nil)
         @http.get("#{BASE}/OrderMetrics", query: date_query(start_date, end_date))
       end
 
+      # Order trend over time. With an API key, requires orders:read.
       def order_trend(start_date: nil, end_date: nil)
         @http.get("#{BASE}/OrderTrend", query: date_query(start_date, end_date))
       end
 
+      # Top selling products. With an API key, requires orders:read.
       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
 
+      # Returns metrics. With an API key, requires returns:read.
       def returns_metrics(start_date: nil, end_date: nil)
         @http.get("#{BASE}/ReturnsMetrics", query: date_query(start_date, end_date))
       end
 
+      # Returns trend over time. With an API key, requires returns:read.
       def returns_trend(start_date: nil, end_date: nil)
         @http.get("#{BASE}/ReturnsTrend", query: date_query(start_date, end_date))
       end
 
+      # Return reasons breakdown. With an API key, requires returns:read.
       def return_reasons(start_date: nil, end_date: nil)
         @http.get("#{BASE}/ReturnReasons", query: date_query(start_date, end_date))
       end
 
+      # Fulfillment performance metrics. With an API key, requires shipping:read.
       def performance_metrics(start_date: nil, end_date: nil)
         @http.get("#{BASE}/PerformanceMetrics", query: date_query(start_date, end_date))
       end
 
+      # Carrier delivery performance. With an API key, requires shipping:read.
       def carrier_performance(start_date: nil, end_date: nil)
         @http.get("#{BASE}/CarrierPerformance", query: date_query(start_date, end_date))
       end
 
+      # Shipping cost analytics. With an API key, requires shipping:read.
       def shipping_cost_analytics(start_date: nil, end_date: nil)
         @http.get("#{BASE}/ShippingCostAnalytics", query: date_query(start_date, end_date))
       end
 
+      # Delivery performance (on-time percentage). With an API key, requires shipping:read.
       def delivery_performance(start_date: nil, end_date: nil)
         @http.get("#{BASE}/DeliveryPerformance", query: date_query(start_date, end_date))
       end

data/lib/flexops/resources/carriers.rb

@@ -9,7 +9,12 @@
 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
+    # Lookups (GET) work with a user token, or an API key that has the permission for the data
+    # they read: address, ZIP, city, location, service point and reference lookups require
+    # shipping:read; tracking and proof of delivery require tracking:read; delivery standards,
+    # rates and products require rates:read. A key without the permission gets 403
+    # API_KEY_SCOPE_REQUIRED; keys created with the default permissions have all three.
+    # 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.
@@ -25,6 +30,9 @@ module FlexOps
       end
     end
 
+    # USPS through the legacy proxy. With an API key, the address, ZIP, city and location lookups
+    # require shipping:read, tracking requires tracking:read and delivery standards require
+    # rates:read.
     class UspsCarrier
       PROXY = "/api/ApiProxy"
 
@@ -52,10 +60,12 @@ module FlexOps
       def get_international_prices(body) = @http.post("#{PROXY}/api/v3/RateCalculator/postUspsSearchEligibleInternationalPrices", 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")
+      def cancel_domestic_label(tracking_number) = cancel("/api/v3/Shipping/cancelUspsDomesticShipmentLabel", "trackingNumber", tracking_number)
       # @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 cancel_international_label(international_tracking_number)
+        cancel("/api/v3/Shipping/cancelUspsInternationalShipmentLabel", "internationalTrackingNumber", international_tracking_number)
+      end
       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
@@ -63,15 +73,25 @@ module FlexOps
       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")
+      def cancel_pickup(confirmation_number) = cancel("/api/v3/CarrierPickup/cancelUspsCarrierPickupSchedule", "confirmationNumber", confirmation_number)
       # @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)
       def find_post_offices(params) = @http.get("#{PROXY}/api/v3/LocationSearch/getUspsFindValidPostOfficeLocations", query: params)
+
+      private
+
+      # Sends a USPS cancel with what it cancels in the query string; without it VSCS answers 400.
+      def cancel(path, param, value)
+        raise ArgumentError, "#{param} is required." if value.to_s.strip.empty?
+
+        @http.delete("#{PROXY}#{path}", query: { param => value })
+      end
     end
 
+    # UPS through the legacy proxy. With an API key, track requires tracking:read.
     class UpsCarrier
       PROXY = "/api/ApiProxy"
 
@@ -178,6 +198,9 @@ module FlexOps
       def confirm_open_shipment(body) = @http.post("#{PROXY}/api/v3/OpenShip/postFedExConfirmOpenShipment", body: body)
     end
 
+    # DHL through the legacy proxy. With an API key, address validation, service points and
+    # reference data require shipping:read; tracking and proof of delivery require
+    # tracking:read; rates and products require rates:read.
     class DhlCarrier
       PROXY = "/api/ApiProxy"
 

data/lib/flexops/resources/inventory.rb

@@ -8,6 +8,10 @@
 
 module FlexOps
   module Resources
+    # Read-only inventory lookups through the legacy /api/ApiProxy passthrough
+    # (/api/ApiProxy/api/v1/Inventory/...). With an API key, every method requires the
+    # inventory:read permission; a key without it gets 403 API_KEY_SCOPE_REQUIRED. Keys created
+    # with the default permissions include inventory:read. The proxy refuses writes from API keys.
     class Inventory
       PROXY = "/api/ApiProxy"
 

data/lib/flexops/resources/orders.rb

@@ -8,6 +8,10 @@
 
 module FlexOps
   module Resources
+    # Read-only order lookups through the legacy /api/ApiProxy passthrough
+    # (/api/ApiProxy/api/v1/Order/...). With an API key, every method requires the orders:read
+    # permission; a key without it gets 403 API_KEY_SCOPE_REQUIRED. Keys created with the default
+    # permissions include orders:read. The proxy refuses writes from API keys.
     class Orders
       BASE = "/api/ApiProxy/api/v1/Order"
 

data/lib/flexops/resources/pickups.rb

@@ -16,6 +16,8 @@ module FlexOps
         @ws_id = ws_id_proc
       end
 
+      # Schedules a carrier pickup. API keys need shipping:write; the public demo keys are refused.
+      #
       # request:: { carrierCode:, pickupDate:, street:, city:, state:, postalCode:,
       #           country: (optional, "US"), packageCount:, totalWeightOz: (optional),
       #           specialInstructions:, readyTime:, closeTime:, contactName:, contactPhone: (all optional) }
@@ -33,6 +35,7 @@ module FlexOps
         @http.get("#{ws_path}/pickups/#{pickup_id}", query: carrier_code.nil? ? nil : { carrierCode: carrier_code })
       end
 
+      # Cancels a scheduled pickup. API keys need shipping:write; the public demo keys are refused.
       # The Gateway uses "usps" when carrier_code is left out.
       def cancel(pickup_id, carrier_code: nil)
         query = carrier_code.nil? ? "" : "?#{URI.encode_www_form(carrierCode: carrier_code)}"

data/lib/flexops/resources/returns.rb

@@ -57,7 +57,9 @@ module FlexOps
       # missing fields.
       #
       # Only what you set is sent; the Gateway uses "usps" when carrier_code is left out.
-      # hazmat_classification (a HazmatClassification) declares what the return holds.
+      # hazmat_classification (a HazmatClassification) declares what the return holds. Return labels
+      # cannot carry HAZMAT yet: send HazmatClassification::NONE or leave it out (any other class is
+      # refused with 400 HazmatNotSupported).
       def generate_label(rma_number, weight_oz: nil, length_in: nil, width_in: nil, height_in: nil,
                          carrier_code: nil, service_type: nil, payment_confirmed: nil, hazmat_classification: nil,
                          rate_indicator: nil)

data/lib/flexops/resources/rules.rb

@@ -24,21 +24,25 @@ module FlexOps
 
       # rule:: { name:, priority:, isEnabled:, warehouseId: (optional),
       #        conditions: [{ field:, operator:, value:, group: (optional) }], actions: [{ type:, value: }] }
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def create(rule)
         @http.post("#{ws_path}/shipping-rules", body: rule)
       end
 
       # rule:: the fields to change, named as for #create.
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def update(rule_id, rule)
         @http.put("#{ws_path}/shipping-rules/#{rule_id}", body: rule)
       end
 
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def delete(rule_id)
         @http.delete("#{ws_path}/shipping-rules/#{rule_id}")
       end
 
       # Sets rule priorities. +rules+ is an array of { ruleId:, priority: } hashes, or of rule ids
       # in the order to apply (the first gets priority 0).
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def reorder(rules)
         items = rules.each_with_index.map do |rule, index|
           rule.is_a?(Hash) ? rule : { ruleId: rule, priority: index }
@@ -47,6 +51,7 @@ module FlexOps
       end
 
       # Evaluates the workspace's rules against a sample shipment without changing anything.
+      # API keys need shipping:read; the public demo keys are refused.
       #
       # request:: { weightOz:, declaredValue:, destinationCountry:, destinationState:,
       #           destinationPostalCode:, orderSource:, itemCount:, shipMethod:, destinationZone:, tags: }

data/lib/flexops/resources/scan_forms.rb

@@ -6,22 +6,66 @@
 # Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
 # ***********************************************************************
 
+require "securerandom"
+
 module FlexOps
   module Resources
+    # USPS SCAN forms. Replies are the Gateway envelope as a Hash with string keys:
+    # { "success" => true, "message" => nil, "data" => form, "errors" => nil, "errorCode" => nil }.
+    # A form (the Gateway's ScanFormDto) has:
+    #
+    # "scanFormId"::       32 hexadecimal digits, no dashes; pass it to #get.
+    # "state"::            FlexOps::ScanFormState::CREATED or OUTCOME_UNKNOWN.
+    # "originPostalCode":: the origin ZIP, or nil.
+    # "trackingNumbers"::  the packages on the form.
+    # "createdAtUtc"::     ISO 8601 in UTC, for example "2026-09-08T21:14:03.512Z".
+    # "scanFormImage"::    the PS Form 5630 PDF, base64; nil for sandbox forms and unresolved
+    #                      operations. FlexOps::ScanFormState.pdf_bytes decodes it.
+    # "manifestNumber"::   the USPS manifest number; "SBOX..." in the sandbox, "" while unresolved.
+    # "manifestDate"::     the mailing date, for example "2026-09-08T00:00:00".
+    # "packageCount"::     how many packages the form covers.
+    # "statusMessage"::    a status line for people.
+    # "success"::          true when "state" is "Created".
+    # "errorMessage"::     not set by the current Gateway; refusals raise FlexOps::Error.
+    # "isSandbox"::        true for a sandbox (test key) form, never sent to USPS.
     class ScanForms
       def initialize(http, ws_id_proc)
         @http = http
         @ws_id = ws_id_proc
       end
 
+      # Creates a USPS SCAN form. API keys need shipping:write; the public demo keys are refused.
+      #
+      # request:: { trackingNumbers: [...] (1 to 1,000), manifestDate: "YYYY-MM-DD",
+      #           requestId: (optional), originPostalCode: (optional), warehouseId: (optional) }
+      #
+      # Live creation needs manifestDate: without it the Gateway answers 400 "Choose the label
+      # mailing date." The sandbox defaults it to today (UTC).
+      #
+      # requestId identifies the operation. Repeating a request with the same ID returns the same
+      # form instead of creating another; reusing it with different inputs is 409. When it is left
+      # out, one is generated for this call and sent on every retry of it, so a retry cannot create
+      # a second form. Pass your own to retry the call yourself after an unknown outcome.
+      #
+      # Returns the envelope whose "data" is the created form, also when the same requestId and
+      # inputs are sent again. Raises FlexOps::Error with status 409 when the requestId was used
+      # with different inputs, when the packages already belong to a manifest, or when this or an
+      # earlier operation needs review (its message names the operation; do not resubmit those
+      # packages), and 400 when the request or package selection is refused. A 409 is not retried.
       def create(request)
-        @http.post("#{ws_path}/scan-forms", body: request)
+        given = request[:requestId] || request["requestId"]
+        body = given ? request : request.reject { |key, _| key.to_s == "requestId" }.merge(requestId: SecureRandom.uuid)
+        @http.post("#{ws_path}/scan-forms", body: body)
       end
 
+      # Lists the workspace's saved scan forms ("data" is an Array of forms), newest mailing date
+      # first, including any whose outcome is unknown.
       def list
         @http.get("#{ws_path}/scan-forms")
       end
 
+      # Gets a saved scan form by its "scanFormId". A form that does not exist raises
+      # FlexOps::Error with status 404.
       def get(scan_form_id)
         @http.get("#{ws_path}/scan-forms/#{scan_form_id}")
       end

data/lib/flexops/resources/shipping.rb

@@ -92,10 +92,16 @@ module FlexOps
       end
 
       # The payload is sent as given. Set hazmatClassification on an item only when you have a declaration.
+      # Batch labels cannot carry HAZMAT yet: send HazmatClassification::NONE or leave hazmatClassification
+      # out (any other class is refused with 400 HazmatNotSupported). Buy HAZMAT labels one at a time
+      # with create_label.
       def create_batch(request)
         @http.post("#{ws_path}/labels/batch", body: request)
       end
 
+      # Previews a batch without buying labels. The payload is sent as given; as with create_batch, an
+      # item's hazmatClassification accepts only HazmatClassification::NONE or nothing (any other class
+      # is refused with 400 HazmatNotSupported).
       def preview_batch(request)
         @http.post("#{ws_path}/labels/batch/preview", body: request)
       end

data/lib/flexops/resources/webhooks.rb

@@ -10,12 +10,29 @@ require "openssl"
 
 module FlexOps
   module Resources
+    # Webhook subscription management and signature verification.
+    #
+    # Every method that calls the Gateway needs a signed-in user's access token
+    # (Client.new(access_token: ...) or Client#set_access_token with the token from
+    # auth.login). The Gateway refuses API keys on every webhook route, reads included,
+    # with 403 SIGNED_IN_USER_REQUIRED, whatever the key's scopes; the SDK raises
+    # FlexOps::Error with that +code+. Reads are refused too because webhook delivery
+    # logs carry each delivery's payload (order and customer data). A client with an API
+    # key sends the key even when an access token is also set, so call these methods
+    # from a client created without +api_key+. verify_signature and verify_signature!
+    # make no request and need no credentials.
     class Webhooks
       def initialize(http, ws_id_proc)
         @http = http
         @ws_id = ws_id_proc
       end
 
+      # Lists the workspace's webhook subscriptions.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED". Reads are
+      # signed-in only, like the writes, because webhook delivery logs carry each
+      # delivery's payload (order and customer data).
       def list
         @http.get("#{ws_path}/webhooks")
       end
@@ -35,6 +52,9 @@ module FlexOps
       # "secret", ...), not a success/data envelope: the Gateway answers 201 with the
       # bare subscription. An enveloped answer is unwrapped, so "secret" (the whsec_...
       # signing secret, returned only here) is always at the top level.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED".
       def create(request)
         unwrap_subscription(@http.post("#{ws_path}/webhooks", body: to_wire_request(request)))
       end
@@ -42,23 +62,43 @@ module FlexOps
       # Updates a webhook subscription. +data+ takes +url+, +description+, +status+
       # ("Active", "Paused" or "Disabled") and +events+, which replaces the subscribed
       # events and is sent as +eventTypes+. Raises ArgumentError as #create does.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED".
       def update(webhook_id, data)
         @http.put("#{ws_path}/webhooks/#{webhook_id}", body: to_wire_request(data))
       end
 
+      # Deletes a webhook subscription.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED".
       def delete(webhook_id)
         @http.delete("#{ws_path}/webhooks/#{webhook_id}")
       end
 
+      # Rotates the subscription's signing secret.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED".
       def rotate_secret(webhook_id)
         @http.post("#{ws_path}/webhooks/#{webhook_id}/rotate-secret")
       end
 
+      # Lists the subscription's delivery logs.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED". Reads are
+      # signed-in only, like the writes, because webhook delivery logs carry each
+      # delivery's payload (order and customer data).
       def list_delivery_logs(webhook_id)
         @http.get("#{ws_path}/webhooks/#{webhook_id}/deliveries")
       end
 
       # Sends a test event (X-FlexOps-Event "test") to the subscription's URL.
+      #
+      # Needs a signed-in user's access token. With an API key the Gateway answers 403
+      # and this raises FlexOps::Error with code "SIGNED_IN_USER_REQUIRED".
       def test(webhook_id)
         @http.post("#{ws_path}/webhooks/#{webhook_id}/test")
       end

data/lib/flexops/resources/workspaces.rb

@@ -29,16 +29,19 @@ module FlexOps
 
       # Invites a member. +role+ is a FlexOps::WorkspaceRole number or name (for example
       # :member); it is required because the Gateway reads a missing role as Owner.
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def invite_member(email:, role:)
         @http.post("/api/workspaces/#{@ws_id.call}/members/invite",
                    body: { email: email, role: FlexOps::WorkspaceRole.to_wire(role) })
       end
 
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def remove_member(user_id)
         @http.delete("/api/workspaces/#{@ws_id.call}/members/#{user_id}")
       end
 
       # Changes a member's role; +role+ is a FlexOps::WorkspaceRole number or name.
+      # Signed-in users only: API keys get 403 SIGNED_IN_USER_REQUIRED, whatever their scopes.
       def update_member_role(user_id, role)
         @http.put("/api/workspaces/#{@ws_id.call}/members/#{user_id}/role",
                   body: { newRole: FlexOps::WorkspaceRole.to_wire(role) })

data/lib/flexops/scan_form_state.rb

@@ -0,0 +1,31 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-10-24
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  # The "state" of a SCAN form hash returned by client.scan_forms (the Gateway's ScanFormDto).
+  # The Gateway may add other values; treat them like OUTCOME_UNKNOWN.
+  module ScanFormState
+    # USPS returned the manifest, and the Gateway saved its number and PDF.
+    CREATED = "Created"
+    # The carrier's answer was lost or did not match. The packages stay reserved: do not submit
+    # them again until the outcome is resolved.
+    OUTCOME_UNKNOWN = "OutcomeUnknown"
+
+    # True when a SCAN form hash ("data" of create/get, or an item of list) is a created form.
+    def self.created?(form)
+      form.is_a?(Hash) && form["state"] == CREATED
+    end
+
+    # Decodes a SCAN form hash's "scanFormImage" (the base64 PS Form 5630 PDF), or returns nil when
+    # it has none: sandbox forms are never sent to USPS, and an unresolved operation has no PDF.
+    def self.pdf_bytes(form)
+      image = form.is_a?(Hash) ? form["scanFormImage"] : nil
+      image.nil? ? nil : image.unpack1("m0")
+    end
+  end
+end

data/lib/flexops/version.rb

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

data/lib/flexops.rb

@@ -11,6 +11,7 @@ require_relative "flexops/errors"
 require_relative "flexops/hazmat_classification"
 require_relative "flexops/webhook_event_type"
 require_relative "flexops/workspace_role"
+require_relative "flexops/scan_form_state"
 require_relative "flexops/http"
 require_relative "flexops/client"
 require_relative "flexops/resources/auth"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flexops
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - FlexOps, LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -87,6 +87,7 @@ files:
 - lib/flexops/resources/wallet.rb
 - lib/flexops/resources/webhooks.rb
 - lib/flexops/resources/workspaces.rb
+- lib/flexops/scan_form_state.rb
 - lib/flexops/version.rb
 - lib/flexops/webhook_event_type.rb
 - lib/flexops/workspace_role.rb