flexops 1.1.0 → 2.1.0

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.1.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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flexops
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.1.0
 platform: ruby
 authors:
 - FlexOps, LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-19 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -66,20 +66,20 @@ files:
 - lib/flexops.rb
 - lib/flexops/client.rb
 - lib/flexops/errors.rb
+- lib/flexops/hazmat_classification.rb
 - lib/flexops/http.rb
 - lib/flexops/resources/analytics.rb
-- lib/flexops/resources/api_keys.rb
 - lib/flexops/resources/auth.rb
+- lib/flexops/resources/carbon_offsets.rb
 - lib/flexops/resources/carriers.rb
 - lib/flexops/resources/email_templates.rb
 - lib/flexops/resources/hs_codes.rb
 - lib/flexops/resources/insurance.rb
 - lib/flexops/resources/inventory.rb
-- lib/flexops/resources/offsets.rb
 - lib/flexops/resources/orders.rb
 - lib/flexops/resources/pickups.rb
 - lib/flexops/resources/recurring_shipments.rb
-- lib/flexops/resources/reports.rb
+- lib/flexops/resources/report_schedules.rb
 - lib/flexops/resources/returns.rb
 - lib/flexops/resources/rules.rb
 - lib/flexops/resources/scan_forms.rb
@@ -88,6 +88,8 @@ files:
 - lib/flexops/resources/webhooks.rb
 - lib/flexops/resources/workspaces.rb
 - lib/flexops/version.rb
+- lib/flexops/webhook_event_type.rb
+- lib/flexops/workspace_role.rb
 homepage: https://github.com/BillEisenman/flexops-sdk-ruby
 licenses:
 - MIT

data/lib/flexops/resources/api_keys.rb

@@ -1,40 +0,0 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-08
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-module FlexOps
-  module Resources
-    class ApiKeys
-      def initialize(http, ws_id_proc)
-        @http = http
-        @ws_id = ws_id_proc
-      end
-
-      def list
-        @http.get("#{ws_path}/api-keys")
-      end
-
-      def create(request)
-        @http.post("#{ws_path}/api-keys", body: request)
-      end
-
-      def revoke(key_id)
-        @http.delete("#{ws_path}/api-keys/#{key_id}")
-      end
-
-      def rotate(key_id)
-        @http.post("#{ws_path}/api-keys/#{key_id}/rotate")
-      end
-
-      private
-
-      def ws_path
-        "/api/workspaces/#{@ws_id.call}"
-      end
-    end
-  end
-end

data/lib/flexops/resources/offsets.rb

@@ -1,38 +0,0 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-31
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-# frozen_string_literal: true
-
-module FlexOps
-  module Resources
-    class Offsets
-      def initialize(http, ws_id_proc)
-        @http = http
-        @ws_id = ws_id_proc
-      end
-
-      def offset(label_id)
-        @http.post("#{ws_path}/shipping/labels/#{label_id}/offset")
-      end
-
-      def get_emissions(label_id)
-        @http.get("#{ws_path}/shipping/labels/#{label_id}/emissions")
-      end
-
-      def batch_offset(label_ids)
-        @http.post("#{ws_path}/shipping/labels/offset/batch", body: { labelIds: label_ids })
-      end
-
-      private
-
-      def ws_path
-        "/api/workspaces/#{@ws_id.call}"
-      end
-    end
-  end
-end

data/lib/flexops/resources/reports.rb

@@ -1,46 +0,0 @@
-# ***********************************************************************
-# Package          : flexops
-# Author           : FlexOps, LLC
-# Created          : 2026-03-31
-#
-# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
-# ***********************************************************************
-
-# frozen_string_literal: true
-
-module FlexOps
-  module Resources
-    class Reports
-      def initialize(http, ws_id_proc)
-        @http = http
-        @ws_id = ws_id_proc
-      end
-
-      def list
-        @http.get("#{ws_path}/report-schedules/")
-      end
-
-      def get(id)
-        @http.get("#{ws_path}/report-schedules/#{id}")
-      end
-
-      def create(request)
-        @http.post("#{ws_path}/report-schedules/", body: request)
-      end
-
-      def update(id, request)
-        @http.put("#{ws_path}/report-schedules/#{id}", body: request)
-      end
-
-      def delete(id)
-        @http.delete("#{ws_path}/report-schedules/#{id}")
-      end
-
-      private
-
-      def ws_path
-        "/api/workspaces/#{@ws_id.call}"
-      end
-    end
-  end
-end