flexops 1.0.2 → 2.0.0

data/lib/flexops/resources/insurance.rb

@@ -8,6 +8,7 @@
 
 module FlexOps
   module Resources
+    # Shipping insurance. Answers use the { success, data, message, errorCode } envelope.
     class Insurance
       def initialize(http, ws_id_proc)
         @http = http
@@ -18,24 +19,33 @@ module FlexOps
         @http.get("#{ws_path}/insurance/providers")
       end
 
-      def get_quote(carrier:, declared_value:, provider: nil)
-        body = { carrier: carrier, declaredValue: declared_value }
-        body[:provider] = provider if provider
+      def get_quote(declared_value:, carrier_code:, tracking_number: nil, provider: nil)
+        body = { declaredValue: declared_value, carrierCode: carrier_code,
+                 trackingNumber: tracking_number, provider: provider }.compact
         @http.post("#{ws_path}/insurance/quote", body: body)
       end
 
-      def purchase(tracking_number:, carrier:, declared_value:, provider: nil)
-        body = { trackingNumber: tracking_number, carrier: carrier, declaredValue: declared_value }
-        body[:provider] = provider if provider
-        @http.post("#{ws_path}/insurance/purchase", body: body)
+      # Buys a policy and charges the premium to the workspace wallet. A shipment that already has a
+      # policy in force is refused with 409 ALREADY_EXISTS.
+      # 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:, carrier_code:, declared_value:, coverage_tier: nil, provider: nil,
+                   idempotency_key: nil)
+        body = { trackingNumber: tracking_number, carrierCode: carrier_code, declaredValue: declared_value,
+                 coverageTier: coverage_tier, provider: provider }.compact
+        @http.post("#{ws_path}/insurance/policies", body: body,
+                   headers: idempotency_key.nil? ? {} : { "Idempotency-Key" => idempotency_key })
       end
 
       def void(policy_id)
         @http.delete("#{ws_path}/insurance/policies/#{policy_id}")
       end
 
-      def file_claim(policy_id, description:, claim_amount:)
-        @http.post("#{ws_path}/insurance/policies/#{policy_id}/claims", body: { description: description, claimAmount: claim_amount })
+      def file_claim(policy_id:, claim_reason:, claim_amount:, evidence_json: nil)
+        body = { policyId: policy_id, claimReason: claim_reason, claimAmount: claim_amount,
+                 evidenceJson: evidence_json }.compact
+        @http.post("#{ws_path}/insurance/claims", body: body)
       end
 
       private

data/lib/flexops/resources/inventory.rb

@@ -15,10 +15,6 @@ module FlexOps
         @http = http
       end
 
-      def post_asn_receipt(receipt)
-        @http.post("#{PROXY}/api/v1/Inventory/postNewAsnReceipt", body: receipt)
-      end
-
       def get_warehouse_snapshot(params = nil)
         @http.get("#{PROXY}/api/v1/Inventory/getWarehouseInventorySnapshot", query: params)
       end
@@ -30,10 +26,6 @@ module FlexOps
       def get_part_numbers(params = nil)
         @http.get("#{PROXY}/api/v1/Inventory/getPartNumberList", query: params)
       end
-
-      def update_inventory(data)
-        @http.post("#{PROXY}/api/v2/Inventory/postCustomerInventoryUpdate", body: data)
-      end
     end
   end
 end

data/lib/flexops/resources/orders.rb

@@ -15,10 +15,6 @@ module FlexOps
         @http = http
       end
 
-      def create(order)
-        @http.post("#{BASE}/postNewOrder", body: order)
-      end
-
       def get_new_orders(params = nil)
         @http.get("#{BASE}/getNewOrderList", query: params)
       end
@@ -39,10 +35,6 @@ module FlexOps
         @http.get("#{BASE}/getIndividualOrderStatusByOrderNumber", query: { orderNumber: order_number })
       end
 
-      def cancel(order_number)
-        @http.post("#{BASE}/cancelOrderByOrderNumber", body: { orderNumber: order_number })
-      end
-
       def get_items(order_number)
         @http.get("#{BASE}/getAllOrderItemsByOrderNumber", query: { orderNumber: order_number })
       end

data/lib/flexops/resources/pickups.rb

@@ -6,6 +6,8 @@
 # Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
 # ***********************************************************************
 
+require "uri"
+
 module FlexOps
   module Resources
     class Pickups
@@ -14,20 +16,27 @@ module FlexOps
         @ws_id = ws_id_proc
       end
 
+      # request:: { carrierCode:, pickupDate:, street:, city:, state:, postalCode:,
+      #           country: (optional, "US"), packageCount:, totalWeightOz: (optional),
+      #           specialInstructions:, readyTime:, closeTime:, contactName:, contactPhone: (all optional) }
       def schedule(request)
         @http.post("#{ws_path}/pickups", body: request)
       end
 
+      # Lists the workspace's scheduled pickups.
       def list
-        @http.get("#{ws_path}/pickups")
+        @http.get("#{ws_path}/pickups/scheduled")
       end
 
-      def get(pickup_id)
-        @http.get("#{ws_path}/pickups/#{pickup_id}")
+      # The Gateway uses "usps" when carrier_code is left out.
+      def get(pickup_id, carrier_code: nil)
+        @http.get("#{ws_path}/pickups/#{pickup_id}", query: carrier_code.nil? ? nil : { carrierCode: carrier_code })
       end
 
-      def cancel(pickup_id)
-        @http.delete("#{ws_path}/pickups/#{pickup_id}")
+      # 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)}"
+        @http.delete("#{ws_path}/pickups/#{pickup_id}#{query}")
       end
 
       private

data/lib/flexops/resources/recurring_shipments.rb

@@ -1,58 +1,73 @@
 # ***********************************************************************
 # 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
+    # Recurring shipment schedules. Answers are bare JSON (no envelope); ids are GUID strings.
+    #
+    # Reads work with any API key or a user token. Writes (create, update, delete, pause, resume,
+    # trigger) need a user token (auth.login) or an API key granted the opt-in
+    # "recurring-shipments:write" scope; a key without it gets 403 API_KEY_SCOPE_REQUIRED.
+    #
+    # +interval+ is the Gateway RecurrenceInterval number: Daily 0, Weekly 1, Biweekly 2,
+    # Monthly 3, Custom 4 (Custom runs on +cronExpression+).
     class RecurringShipments
       def initialize(http, ws_id_proc)
         @http = http
         @ws_id = ws_id_proc
       end
 
-      def list(page: nil, page_size: nil, is_active: nil)
-        query = { page: page, pageSize: page_size, isActive: is_active }.compact
-        @http.get("#{ws_path}/recurring-shipments/", query: query.empty? ? nil : query)
+      def list
+        @http.get(ws_path)
       end
 
       def get(id)
-        @http.get("#{ws_path}/recurring-shipments/#{id}")
+        @http.get("#{ws_path}/#{id}")
       end
 
+      # request:: { name:, firstRunUtc: (ISO 8601), interval: (0-4), presetId:, addressId:,
+      #           cronExpression:, maxFailures: (1-100, default 3) }. Each run needs a destination
+      #           +addressId+; a +presetId+ supplies the package and service. Returns the schedule.
       def create(request)
-        @http.post("#{ws_path}/recurring-shipments/", body: request)
+        @http.post(ws_path, body: request)
       end
 
+      # request:: any of name:, presetId:, addressId:, interval:, cronExpression:, maxFailures:.
       def update(id, request)
-        @http.put("#{ws_path}/recurring-shipments/#{id}", body: request)
+        @http.put("#{ws_path}/#{id}", body: request)
       end
 
+      # Returns nil (204).
       def delete(id)
-        @http.delete("#{ws_path}/recurring-shipments/#{id}")
+        @http.delete("#{ws_path}/#{id}")
       end
 
+      # Returns nil (204).
       def pause(id)
-        @http.post("#{ws_path}/recurring-shipments/#{id}/pause")
+        @http.post("#{ws_path}/#{id}/pause")
       end
 
+      # Returns nil (204).
       def resume(id)
-        @http.post("#{ws_path}/recurring-shipments/#{id}/resume")
+        @http.post("#{ws_path}/#{id}/resume")
       end
 
-      def trigger(id)
-        @http.post("#{ws_path}/recurring-shipments/#{id}/trigger")
+      # Runs the schedule now, which creates an order. Pass the same +idempotency_key+ when you
+      # retry a trigger yourself so the Gateway does not create a second order. Returns nil (204).
+      def trigger(id, idempotency_key: nil)
+        @http.post("#{ws_path}/#{id}/trigger",
+                   headers: idempotency_key.nil? ? {} : { "Idempotency-Key" => idempotency_key })
       end
 
       private
 
       def ws_path
-        "/api/workspaces/#{@ws_id.call}"
+        "/api/workspaces/#{@ws_id.call}/recurring-shipments"
       end
     end
   end

data/lib/flexops/resources/report_schedules.rb

@@ -0,0 +1,63 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-10-19
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    # Scheduled report emails. Answers use the { success, data, message } envelope, except
+    # delete, which returns nil (204). Ids are GUID strings.
+    #
+    # Reads work with any API key or a user token. Writes (create, update, delete, toggle) need a
+    # user token (auth.login) or an API key granted the opt-in "report-schedules:write" scope; a
+    # key without it gets 403 API_KEY_SCOPE_REQUIRED.
+    #
+    # Numbers on the wire: +format+ Csv 0, Json 1; +frequencyType+ Daily 0, Weekly 1, Monthly 2;
+    # +dayOfWeek+ 0-6 (Sunday 0, for Weekly); +dayOfMonth+ 1-28 (for Monthly).
+    class ReportSchedules
+      def initialize(http, ws_id_proc)
+        @http = http
+        @ws_id = ws_id_proc
+      end
+
+      def list
+        @http.get(ws_path)
+      end
+
+      def get(id)
+        @http.get("#{ws_path}/#{id}")
+      end
+
+      # request:: { reportType: (e.g. "shipments"), format:, frequencyType:, timeOfDayUtc: ("HH:mm:ss"),
+      #           recipientEmails: (comma-separated), dayOfWeek:, dayOfMonth:, filterParametersJson:,
+      #           maxFailures: (1-100, default 3) }.
+      def create(request)
+        @http.post(ws_path, body: request)
+      end
+
+      # request:: any of the create fields.
+      def update(id, request)
+        @http.put("#{ws_path}/#{id}", body: request)
+      end
+
+      # Returns nil (204).
+      def delete(id)
+        @http.delete("#{ws_path}/#{id}")
+      end
+
+      # Flips isEnabled. The envelope's data is nil; read the schedule to see the new state.
+      def toggle(id)
+        @http.post("#{ws_path}/#{id}/toggle")
+      end
+
+      private
+
+      def ws_path
+        "/api/workspaces/#{@ws_id.call}/report-schedules"
+      end
+    end
+  end
+end

data/lib/flexops/resources/returns.rb

@@ -14,8 +14,8 @@ module FlexOps
         @ws_id = ws_id_proc
       end
 
-      def list(page: nil, page_size: nil, status: nil)
-        query = { page: page, pageSize: page_size, status: status }.compact
+      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
 
@@ -23,32 +23,46 @@ module FlexOps
         @http.get("#{ws_path}/returns/#{return_id}")
       end
 
+      # Creates an RMA and returns the enveloped RMA (201).
+      #
+      # request:: { orderId: (a number), orderNumber: (optional), reason:,
+      #           items: [{ sku:, quantity:, reason: (optional) }], notes: (optional),
+      #           customerEmail: (optional), reasonId: (optional) }
       def create(request)
-        @http.post("#{ws_path}/returns", body: request)
+        @http.post("#{ws_path}/returns/rma", body: request)
       end
 
-      def approve(return_id)
-        @http.post("#{ws_path}/returns/#{return_id}/approve")
+      # Generates a return label for an RMA.
+      #
+      # The carrier needs the package weight and all three dimensions: pass weight_oz, length_in,
+      # width_in and height_in. Anything left out comes from the workspace's default shipping
+      # preset; with no preset the Gateway answers 400 PackageMeasurementsRequired naming the
+      # 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.
+      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)
+        # Always a JSON object: the Gateway binds a required GenerateReturnLabelRequest body and refuses an empty one with 400.
+        body = {
+          carrierCode: carrier_code, serviceType: service_type, weightOz: weight_oz, lengthIn: length_in,
+          widthIn: width_in, heightIn: height_in, paymentConfirmed: payment_confirmed,
+          hazmatClassification: hazmat_classification, rateIndicator: rate_indicator
+        }.compact
+        @http.post("#{ws_path}/returns/#{rma_number}/label", body: body)
       end
 
-      def reject(return_id, reason)
-        @http.post("#{ws_path}/returns/#{return_id}/reject", body: { reason: reason })
-      end
-
-      def cancel(return_id)
-        @http.post("#{ws_path}/returns/#{return_id}/cancel")
-      end
-
-      def generate_label(return_id)
-        @http.post("#{ws_path}/returns/#{return_id}/label")
-      end
-
-      def mark_received(return_id, items)
-        @http.post("#{ws_path}/returns/#{return_id}/receive", body: { items: items })
-      end
-
-      def process_refund(return_id)
-        @http.post("#{ws_path}/returns/#{return_id}/refund")
+      # Records the inspected items of a received RMA.
+      #
+      # rma_id::          the numeric RMA id (the route segment)
+      # rma_number::      the RMA number, for example "RMA-1001"
+      # inspected_items:: [{ partNumber:, partDescription: (optional), quantity:,
+      #                   disposition: 0 restock, 1 dispose or 2 forward, inspectionNotes: (optional) }]
+      # warehouse_id::    the receiving warehouse; the Gateway uses 1 when it is left out
+      def mark_received(rma_id, rma_number:, inspected_items:, warehouse_id: nil)
+        body = { rmaNumber: rma_number, warehouseId: warehouse_id, inspectedItems: inspected_items }.compact
+        @http.post("#{ws_path}/returns/#{rma_id}/receive", body: body)
       end
 
       private

data/lib/flexops/resources/rules.rb

@@ -22,10 +22,13 @@ module FlexOps
         @http.get("#{ws_path}/shipping-rules/#{rule_id}")
       end
 
+      # rule:: { name:, priority:, isEnabled:, warehouseId: (optional),
+      #        conditions: [{ field:, operator:, value:, group: (optional) }], actions: [{ type:, value: }] }
       def create(rule)
         @http.post("#{ws_path}/shipping-rules", body: rule)
       end
 
+      # rule:: the fields to change, named as for #create.
       def update(rule_id, rule)
         @http.put("#{ws_path}/shipping-rules/#{rule_id}", body: rule)
       end
@@ -34,8 +37,21 @@ module FlexOps
         @http.delete("#{ws_path}/shipping-rules/#{rule_id}")
       end
 
-      def reorder(rule_ids)
-        @http.put("#{ws_path}/shipping-rules/reorder", body: rule_ids)
+      # 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).
+      def reorder(rules)
+        items = rules.each_with_index.map do |rule, index|
+          rule.is_a?(Hash) ? rule : { ruleId: rule, priority: index }
+        end
+        @http.post("#{ws_path}/shipping-rules/reorder", body: { rules: items })
+      end
+
+      # Evaluates the workspace's rules against a sample shipment without changing anything.
+      #
+      # request:: { weightOz:, declaredValue:, destinationCountry:, destinationState:,
+      #           destinationPostalCode:, orderSource:, itemCount:, shipMethod:, destinationZone:, tags: }
+      def test(request)
+        @http.post("#{ws_path}/shipping-rules/test", body: request)
       end
 
       private

data/lib/flexops/resources/shipping.rb

@@ -6,6 +6,8 @@
 # Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
 # ***********************************************************************
 
+require "erb"
+
 module FlexOps
   module Resources
     class Shipping
@@ -26,22 +28,39 @@ 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.
+      # A label without an orderId must declare hazmatClassification (a HazmatClassification;
+      # HazmatClassification::NONE for an ordinary parcel). The SDK never fills it in.
+      def create_label(request = {}, idempotency_key: nil, **fields)
+        request = request.merge(fields)
+        @http.post("/api/shipping/labels", body: request,
+                   headers: idempotency_key.nil? ? {} : { "Idempotency-Key" => idempotency_key })
       end
 
-      def cancel_label(label_id)
-        @http.delete("#{ws_path}/shipping/labels/#{label_id}")
+      # The Gateway requires the carrier code (for example "USPS"). It is a keyword with no
+      # default value so older call sites fail with a clear ArgumentError before any request.
+      def cancel_label(label_id, carrier_code: nil)
+        raise ArgumentError, "carrier_code is required to cancel a label (for example \"USPS\")" if carrier_code.to_s.empty?
+
+        @http.delete("/api/shipping/labels/#{escape(label_id)}?carrierCode=#{escape(carrier_code)}")
       end
 
       def track(tracking_number)
-        @http.get("#{ws_path}/shipping/track/#{tracking_number}")
+        @http.get("/api/shipping/track/#{escape(tracking_number)}")
       end
 
+      # Validates an address with POST /api/addresses/validate and returns the bare result
+      # ("isValid", "validationUnavailable", "suggestedAddress", "isResidential", "warnings",
+      # "validatedBy", "checkedAt").
+      #
+      # The address may use the rate and label field names (addressLine1, stateProvince,
+      # countryCode, ...), the legacy street1/state/zip names, or the Gateway's own
+      # (line1, line2, city, state, postalCode, country). Only those fields and name are sent.
       def validate_address(address)
-        @http.post("#{ws_path}/shipping/addresses/validate", body: address)
+        @http.post("/api/addresses/validate", body: to_validation_address(address))
       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)
       end
@@ -59,19 +78,19 @@ module FlexOps
       end
 
       def get_carriers
-        @http.get("#{ws_path}/shipping/carriers")
+        @http.get("/api/shipping/carriers")
       end
 
       def get_recommendations(request)
-        @http.post("#{ws_path}/shipping/recommendations", body: request)
+        @http.post("/api/shipping/recommendations", body: request)
       end
 
       def predict_delivery(request)
-        @http.post("#{ws_path}/shipping/predictions/delivery", body: request)
+        @http.post("/api/shipping/predictions/delivery", body: request)
       end
 
       def get_savings
-        @http.get("#{ws_path}/shipping/savings")
+        @http.get("/api/shipping/savings")
       end
 
       private
@@ -79,6 +98,28 @@ module FlexOps
       def ws_path
         "/api/workspaces/#{@ws_id.call}"
       end
+
+      def escape(segment)
+        ERB::Util.url_encode(segment.to_s)
+      end
+
+      # Gateway AddressValidationRequest field for each accepted address field name.
+      VALIDATION_ADDRESS_FIELDS = {
+        "name" => "name",
+        "line1" => "line1", "addressLine1" => "line1", "street1" => "line1",
+        "line2" => "line2", "addressLine2" => "line2", "street2" => "line2",
+        "city" => "city",
+        "state" => "state", "stateProvince" => "state",
+        "postalCode" => "postalCode", "zip" => "postalCode",
+        "country" => "country", "countryCode" => "country"
+      }.freeze
+
+      def to_validation_address(address)
+        address.each_with_object({}) do |(key, value), mapped|
+          field = VALIDATION_ADDRESS_FIELDS[key.to_s]
+          mapped[field] = value unless field.nil? || value.nil?
+        end
+      end
     end
   end
 end

data/lib/flexops/resources/wallet.rb

@@ -14,27 +14,11 @@ module FlexOps
         @ws_id = ws_id_proc
       end
 
+      # Returns the configured workspace's balance, bare: { "hasWallet", "balanceCents", "balance" }.
+      # Funding and transaction history are managed in the FlexOps portal.
       def get_balance
-        @http.get("#{ws_path}/wallet/balance")
-      end
-
-      def add_funds(amount)
-        @http.post("#{ws_path}/wallet/add-funds", body: { amount: amount })
-      end
-
-      def list_transactions(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}/wallet/transactions", query: query.empty? ? nil : query)
-      end
-
-      def configure_auto_reload(enabled:, threshold: nil, amount: nil)
-        @http.put("#{ws_path}/wallet/auto-reload", body: { enabled: enabled, threshold: threshold, amount: amount }.compact)
-      end
-
-      private
-
-      def ws_path
-        "/api/workspaces/#{@ws_id.call}"
+        ws_id = @ws_id.call
+        @http.get("/api/wallet/my-balance", headers: ws_id.to_s.empty? ? {} : { "X-Workspace-Id" => ws_id.to_s })
       end
     end
   end