flexops 1.1.0 → 2.0.0

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
@@ -27,24 +29,38 @@ module FlexOps
       end
 
       # 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("#{ws_path}/shipping/labels", body: request,
+        @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
@@ -62,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
@@ -82,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

data/lib/flexops/resources/webhooks.rb

@@ -20,16 +20,30 @@ module FlexOps
         @http.get("#{ws_path}/webhooks")
       end
 
-      def get(webhook_id)
-        @http.get("#{ws_path}/webhooks/#{webhook_id}")
-      end
-
+      # Creates a webhook subscription.
+      #
+      # request:: a hash with +url+, optional +description+ and optional +events+, an
+      #           array of FlexOps::WebhookEventType names (strings or symbols). +events+
+      #           is sent as the Gateway's comma-separated +eventTypes+; leave it out to
+      #           receive every event. A raw +eventTypes+ string ("*" or comma-separated
+      #           names, no spaces) is sent unchanged instead.
+      #
+      # Raises ArgumentError, before any request, when +events+ is empty, is not an
+      # array, names an event FlexOps does not send, or is given with +eventTypes+.
+      #
+      # Returns the new subscription itself ("id", "url", "eventTypes", "status",
+      # "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.
       def create(request)
-        @http.post("#{ws_path}/webhooks", body: request)
+        unwrap_subscription(@http.post("#{ws_path}/webhooks", body: to_wire_request(request)))
       end
 
+      # 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.
       def update(webhook_id, data)
-        @http.put("#{ws_path}/webhooks/#{webhook_id}", body: data)
+        @http.put("#{ws_path}/webhooks/#{webhook_id}", body: to_wire_request(data))
       end
 
       def delete(webhook_id)
@@ -44,9 +58,74 @@ module FlexOps
         @http.get("#{ws_path}/webhooks/#{webhook_id}/deliveries")
       end
 
-      def self.verify_signature(payload, signature, secret)
-        expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
-        OpenSSL.secure_compare(expected, signature)
+      # Sends a test event (X-FlexOps-Event "test") to the subscription's URL.
+      def test(webhook_id)
+        @http.post("#{ws_path}/webhooks/#{webhook_id}/test")
+      end
+
+      # Headers FlexOps sends with every webhook delivery.
+      EVENT_HEADER = "X-FlexOps-Event"         # event name; "test" for a test event
+      EVENT_ID_HEADER = "X-FlexOps-Event-Id"
+      TIMESTAMP_HEADER = "X-FlexOps-Timestamp" # Unix seconds, part of the signed string
+      SIGNATURE_HEADER = "X-FlexOps-Signature" # "sha256=" + lowercase hex HMAC-SHA256
+      DELIVERY_HEADER = "X-FlexOps-Delivery"
+
+      # Seconds the X-FlexOps-Timestamp may be from now, either way.
+      DEFAULT_TOLERANCE = 300
+
+      SIGNATURE_PREFIX = "sha256="
+      private_constant :SIGNATURE_PREFIX
+
+      # Returns true when a FlexOps webhook delivery is authentic and fresh,
+      # false otherwise. See verify_signature! for the arguments.
+      def self.verify_signature(payload:, signature:, timestamp:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+        verify_signature!(payload: payload, signature: signature, timestamp: timestamp,
+                          secret: secret, tolerance: tolerance, now: now)
+      rescue FlexOps::WebhookSignatureError
+        false
+      end
+
+      # Verifies a FlexOps webhook delivery and returns true, or raises
+      # FlexOps::WebhookSignatureError saying why.
+      #
+      # payload::   the raw request body exactly as received (verify before parsing it)
+      # signature:: the X-FlexOps-Signature value, "sha256=<hex>" (bare hex is accepted)
+      # timestamp:: the X-FlexOps-Timestamp value, Unix seconds
+      # secret::    the subscription secret ("whsec_..."), used as-is
+      # tolerance:: seconds the timestamp may be from +now+; non-positive keeps the default
+      # now::       the current time (a Time or Unix seconds), for tests
+      #
+      # FlexOps signs "{timestamp}.{body}" with HMAC-SHA256; the comparison is
+      # constant time.
+      def self.verify_signature!(payload:, signature:, timestamp:, secret:, tolerance: DEFAULT_TOLERANCE, now: Time.now)
+        if secret.nil? || secret.to_s.empty?
+          raise FlexOps::WebhookSignatureError.new("Webhook secret is empty", code: "WEBHOOK_MISSING_SECRET")
+        end
+        if signature.nil? || signature.to_s.empty?
+          raise FlexOps::WebhookSignatureError.new("Webhook signature header is missing", code: "WEBHOOK_MISSING_SIGNATURE")
+        end
+
+        timestamp = timestamp.to_s
+        unless timestamp.match?(/\A\d+\z/)
+          raise FlexOps::WebhookSignatureError.new("Webhook timestamp header is missing or not Unix seconds",
+                                                   code: "WEBHOOK_INVALID_TIMESTAMP")
+        end
+
+        tolerance = DEFAULT_TOLERANCE unless tolerance.is_a?(Numeric) && tolerance.positive?
+        if (now.to_i - timestamp.to_i).abs > tolerance
+          raise FlexOps::WebhookSignatureError.new("Webhook timestamp is outside the tolerance",
+                                                   code: "WEBHOOK_TIMESTAMP_OUTSIDE_TOLERANCE")
+        end
+
+        signed = "#{timestamp}.".b << payload.to_s.b
+        expected = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, signed)
+        received = signature.to_s.delete_prefix(SIGNATURE_PREFIX).downcase
+        # OpenSSL.secure_compare hashes both sides first, so unequal lengths are safe.
+        unless OpenSSL.secure_compare(expected, received)
+          raise FlexOps::WebhookSignatureError.new("Webhook signature does not match", code: "WEBHOOK_SIGNATURE_MISMATCH")
+        end
+
+        true
       end
 
       private
@@ -54,6 +133,50 @@ module FlexOps
       def ws_path
         "/api/workspaces/#{@ws_id.call}"
       end
+
+      # The Gateway reads a comma-separated eventTypes string, ignores an events field
+      # (subscribing to every event) and matches each name exactly, so a name it never
+      # sends would leave the subscription silent; it is refused here instead.
+      def to_wire_request(request)
+        return request unless request.is_a?(Hash)
+
+        events_key = [:events, "events"].find { |key| request.key?(key) }
+        return request if events_key.nil?
+
+        body = request.reject { |key, _| key == events_key }
+        events = request[events_key]
+        return body if events.nil?
+
+        if [:eventTypes, "eventTypes"].any? { |key| body.key?(key) }
+          raise ArgumentError, "Pass events or eventTypes, not both."
+        end
+
+        body.merge(eventTypes: to_event_types(events))
+      end
+
+      def unwrap_subscription(response)
+        return response unless response.is_a?(Hash) && response.key?("success") && response["data"].is_a?(Hash)
+
+        response["data"]
+      end
+
+      def to_event_types(events)
+        unless events.is_a?(Array)
+          raise ArgumentError, "events must be an array of event names, not #{events.class}."
+        end
+        if events.empty?
+          raise ArgumentError, "events must name at least one event; leave it out to receive every event."
+        end
+
+        names = events.map { |event| event.is_a?(String) || event.is_a?(Symbol) ? event.to_s : event.inspect }.uniq
+        unknown = names - FlexOps::WebhookEventType::ALL
+        unless unknown.empty?
+          raise ArgumentError, "Unknown webhook event: #{unknown.join(", ")}. " \
+                               "FlexOps sends #{FlexOps::WebhookEventType::ALL.join(", ")}."
+        end
+
+        names.join(",")
+      end
     end
   end
 end

data/lib/flexops/resources/workspaces.rb

@@ -23,30 +23,25 @@ module FlexOps
         @http.get("/api/workspaces/#{id}")
       end
 
-      def create(request)
-        @http.post("/api/workspaces", body: request)
-      end
-
-      def update(data)
-        @http.put("/api/workspaces/#{@ws_id.call}", body: data)
-      end
-
       def list_members
         @http.get("/api/workspaces/#{@ws_id.call}/members")
       end
 
-      def invite_member(email:, role: nil)
-        body = { email: email }
-        body[:role] = role if role
-        @http.post("/api/workspaces/#{@ws_id.call}/members/invite", body: body)
+      # 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.
+      def invite_member(email:, role:)
+        @http.post("/api/workspaces/#{@ws_id.call}/members/invite",
+                   body: { email: email, role: FlexOps::WorkspaceRole.to_wire(role) })
       end
 
       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.
       def update_member_role(user_id, role)
-        @http.put("/api/workspaces/#{@ws_id.call}/members/#{user_id}/role", body: { role: role })
+        @http.put("/api/workspaces/#{@ws_id.call}/members/#{user_id}/role",
+                  body: { newRole: FlexOps::WorkspaceRole.to_wire(role) })
       end
     end
   end

data/lib/flexops/version.rb

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

data/lib/flexops/webhook_event_type.rb

@@ -0,0 +1,25 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-10-16
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  # Event names FlexOps sends in the X-FlexOps-Event header and matches webhook
+  # subscriptions against.
+  #
+  # Names are PascalCase and matched exactly: a dotted name such as "label.created"
+  # matches nothing. TRACKING_UPDATED and TRACKING_DELIVERED are sent only to
+  # workspaces in the USPS push-tracking pilot.
+  module WebhookEventType
+    LABEL_CREATED = "LabelCreated"
+    LABEL_CANCELED = "LabelCanceled"
+    BATCH_COMPLETED = "BatchCompleted"
+    TRACKING_UPDATED = "TrackingUpdated"
+    TRACKING_DELIVERED = "TrackingDelivered"
+
+    ALL = [LABEL_CREATED, LABEL_CANCELED, BATCH_COMPLETED, TRACKING_UPDATED, TRACKING_DELIVERED].freeze
+  end
+end

data/lib/flexops/workspace_role.rb

@@ -0,0 +1,32 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-10-19
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  # Workspace member role, sent as the Gateway WorkspaceRole number.
+  module WorkspaceRole
+    OWNER = 0
+    ADMIN = 1
+    MEMBER = 2
+    MERCHANT = 3
+
+    ALL = { OWNER: OWNER, ADMIN: ADMIN, MEMBER: MEMBER, MERCHANT: MERCHANT }.freeze
+
+    # Returns the wire number for a role given as a number or a name (:member, "Admin").
+    # Raises ArgumentError, before any request, for anything else.
+    def self.to_wire(role)
+      return role if role.is_a?(Integer) && ALL.value?(role)
+
+      if role.is_a?(String) || role.is_a?(Symbol)
+        number = ALL[role.to_s.upcase.to_sym]
+        return number unless number.nil?
+      end
+
+      raise ArgumentError, "Unknown workspace role: #{role.inspect}. Use one of #{ALL.keys.join(", ")} or 0-3."
+    end
+  end
+end

data/lib/flexops.rb

@@ -8,6 +8,9 @@
 
 require_relative "flexops/version"
 require_relative "flexops/errors"
+require_relative "flexops/hazmat_classification"
+require_relative "flexops/webhook_event_type"
+require_relative "flexops/workspace_role"
 require_relative "flexops/http"
 require_relative "flexops/client"
 require_relative "flexops/resources/auth"
@@ -18,18 +21,17 @@ require_relative "flexops/resources/webhooks"
 require_relative "flexops/resources/wallet"
 require_relative "flexops/resources/insurance"
 require_relative "flexops/resources/returns"
-require_relative "flexops/resources/api_keys"
 require_relative "flexops/resources/analytics"
 require_relative "flexops/resources/orders"
 require_relative "flexops/resources/inventory"
 require_relative "flexops/resources/pickups"
 require_relative "flexops/resources/scan_forms"
 require_relative "flexops/resources/rules"
-require_relative "flexops/resources/offsets"
 require_relative "flexops/resources/hs_codes"
+require_relative "flexops/resources/carbon_offsets"
 require_relative "flexops/resources/recurring_shipments"
+require_relative "flexops/resources/report_schedules"
 require_relative "flexops/resources/email_templates"
-require_relative "flexops/resources/reports"
 
 module FlexOps
 end