flexops 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de7a8ef21d6a80d52efbbb2f7254fb5184c875ab84a09834204d4757736040ce
+  data.tar.gz: 741a555c559275fe53124fa44d5cd76d3d9dbf57031b12346dfecb63e9c26c73
+SHA512:
+  metadata.gz: e32d5a2172b700037fe706867b7111a5f6af66d099bf8f759b916fb38134b7760a3212d2f44c6eec83a10b243cf602c2fadd20792884871fbdcc878b84306f8c
+  data.tar.gz: 4446a9a607aba3ccc55b694f4438a63d6d20422825a7bd476da37dad4021885e60d2b93e65f6cf72ef65eb9ac4b930f2afd0a4fc26361a651f877be185ed6a7f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlexOps, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# FlexOps Ruby SDK
+
+Official Ruby SDK for the [FlexOps](https://flexops.io) multi-carrier shipping platform. Supports USPS, UPS, FedEx, DHL, OnTrac, Australia Post, Canada Post, Royal Mail, and LSO with rate shopping, label generation, tracking, webhooks, wallet, insurance, returns, and more.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "flexops"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install flexops
+```
+
+## Quick Start
+
+```ruby
+require "flexops"
+
+# API key authentication (recommended for server-to-server)
+client = FlexOps::Client.new(
+  api_key: "fxk_live_...",
+  workspace_id: "ws_abc123"
+)
+
+# Get shipping rates from all carriers
+rates = client.shipping.get_rates(
+  from_address: {street1: "123 Main St", city: "New York", state: "NY", zip: "10001", country: "US"},
+  to_address:   {street1: "456 Oak Ave", city: "Los Angeles", state: "CA", zip: "90210", country: "US"},
+  parcel:       {weight: 16, weight_unit: "oz"}
+)
+
+# Create a label with the cheapest rate
+cheapest = rates["data"].min_by { |r| r["totalCost"].to_f }
+label = client.shipping.create_label(
+  carrier:      cheapest["carrier"],
+  service:      cheapest["service"],
+  from_address: {name: "Warehouse", street1: "123 Main St", city: "New York", state: "NY", zip: "10001", country: "US"},
+  to_address:   {name: "Customer",  street1: "456 Oak Ave", city: "Los Angeles", state: "CA", zip: "90210", country: "US"},
+  parcel:       {weight: 16, weight_unit: "oz"}
+)
+
+puts "Label URL: #{label["data"]["labelUrl"]}"
+puts "Tracking:  #{label["data"]["trackingNumber"]}"
+
+# Track a shipment
+info = client.shipping.track("9400111899223456789012")
+```
+
+## Authentication
+
+### API key (recommended)
+
+```ruby
+client = FlexOps::Client.new(api_key: "fxk_live_...", workspace_id: "ws_abc123")
+```
+
+### Email / password
+
+```ruby
+client = FlexOps::Client.new(base_url: "https://gateway.flexops.io")
+client.auth.login(email: "user@example.com", password: "password")
+client.workspace_id = "ws_abc123"
+```
+
+## Sandbox / test keys
+
+Use `fxk_test_...` (instead of `fxk_live_...`) to route to the sandbox environment. Mock carriers respond, nothing hits real carrier APIs, no charges, no real labels. Perfect for CI and integration tests.
+
+```ruby
+client = FlexOps::Client.new(api_key: "fxk_test_...", workspace_id: "ws_abc123")
+```
+
+## Direct carrier operations
+
+Access carrier-specific endpoints when you need full control:
+
+```ruby
+# USPS domestic label
+label = client.carriers.usps.create_domestic_label(
+  image_type: "PDF",
+  mail_class: "PRIORITY_MAIL",
+  weight_in_ounces: 16
+)
+
+# FedEx rate quote
+rates = client.carriers.fedex.get_rates(...)
+
+# UPS tracking
+info = client.carriers.ups.track(tracking_number: "1Z999AA10123456784")
+
+# DHL shipment
+shipment = client.carriers.dhl.create_shipment(...)
+```
+
+## Webhook verification
+
+```ruby
+valid = FlexOps::Resources::Webhooks.verify_signature(
+  payload:   request.body.read,
+  signature: request.headers["X-FlexOps-Signature"],
+  secret:    "whsec_..."
+)
+```
+
+## Curl quickstart
+
+Every SDK method is a thin wrapper around the FlexOps REST API. If you want to verify the API before committing to the SDK — or you're integrating from a language we don't ship a SDK for — these curl invocations hit the same endpoints:
+
+```bash
+# Shop rates across all connected carriers
+curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/rates \
+  -H "X-API-Key: fxk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fromAddress": {"street1": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "country": "US"},
+    "toAddress":   {"street1": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip": "90210", "country": "US"},
+    "parcel":      {"weight": 16, "weightUnit": "oz"}
+  }'
+
+# Create a label
+curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/labels \
+  -H "X-API-Key: fxk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "carrier":  "USPS",
+    "service":  "PRIORITY_MAIL",
+    "fromAddress": {"name": "Warehouse", "street1": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "country": "US"},
+    "toAddress":   {"name": "Customer",  "street1": "456 Oak Ave", "city": "Los Angeles", "state": "CA", "zip": "90210", "country": "US"},
+    "parcel":   {"weight": 16, "weightUnit": "oz"}
+  }'
+
+# Track a shipment
+curl https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/track/9400111899223456789012 \
+  -H "X-API-Key: fxk_live_..."
+
+# Cancel a label (via the unified carrier-agnostic endpoint)
+curl -X DELETE https://gateway.flexops.io/api/v3.0/shipping/Usps/cancel/9400111899223456789012 \
+  -H "X-API-Key: fxk_live_..."
+```
+
+Use an `fxk_test_...` key instead of `fxk_live_...` to hit the sandbox environment; mock carriers respond, no real charges, no real labels.
+
+## Resources
+
+| Resource | Description |
+|----------|-------------|
+| `client.auth` | Login, register, password management |
+| `client.workspaces` | Workspace CRUD, membership, branding |
+| `client.shipping` | Rate shopping, labels, tracking, batch, cancel |
+| `client.carriers` | USPS, UPS, FedEx, DHL direct endpoints |
+| `client.webhooks` | Subscription CRUD, signature verification, delivery logs |
+| `client.wallet` | Balance, transactions, auto-reload |
+| `client.insurance` | Quotes, purchase, claims (first-party + U-PIC) |
+| `client.returns` | RMA lifecycle: create, batch, QR codes, photo upload, cost recovery |
+| `client.api_keys` | Key creation, rotation, revocation |
+| `client.analytics` | Shipments, orders, carrier performance |
+| `client.orders` | Order management |
+| `client.inventory` | Warehouse inventory |
+| `client.pickups` | Carrier pickup scheduling |
+| `client.scan_forms` | USPS scan forms |
+| `client.rules` | Shipping automation rules |
+| `client.offsets` | Carbon offset purchases |
+| `client.hs_codes` | HS code lookup for international customs |
+| `client.recurring_shipments` | Scheduled recurring shipments |
+| `client.email_templates` | Branded post-purchase email templates |
+| `client.reports` | Report generation and scheduled delivery |
+
+## Configuration
+
+```ruby
+client = FlexOps::Client.new(
+  base_url:     "https://gateway.flexops.io",  # API base URL
+  api_key:      "fxk_live_...",            # API key auth
+  workspace_id: "ws_abc123",               # Default workspace
+  timeout:      30                         # Request timeout (seconds)
+)
+```
+
+## Requirements
+
+- Ruby 3.0+
+
+## License
+
+Proprietary — FlexOps, LLC

data/lib/flexops/client.rb

@@ -0,0 +1,53 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  class Client
+    attr_accessor :workspace_id
+    attr_reader :auth, :workspaces, :shipping, :carriers, :webhooks, :wallet,
+                :insurance, :returns, :api_keys, :analytics, :orders, :inventory,
+                :pickups, :scan_forms, :rules, :offsets, :hs_codes,
+                :recurring_shipments, :email_templates, :reports
+
+    def initialize(api_key: nil, access_token: nil, base_url: "https://gateway.flexops.io", workspace_id: nil, timeout: 30)
+      @http = HttpClient.new(base_url: base_url, api_key: api_key, access_token: access_token, timeout: timeout)
+      @workspace_id = workspace_id
+
+      ws_id_proc = -> { @workspace_id }
+
+      @auth = Resources::Auth.new(@http)
+      @workspaces = Resources::Workspaces.new(@http, ws_id_proc)
+      @shipping = Resources::Shipping.new(@http, ws_id_proc)
+      @carriers = Resources::Carriers.new(@http)
+      @webhooks = Resources::Webhooks.new(@http, ws_id_proc)
+      @wallet = Resources::Wallet.new(@http, ws_id_proc)
+      @insurance = Resources::Insurance.new(@http, ws_id_proc)
+      @returns = Resources::Returns.new(@http, ws_id_proc)
+      @api_keys = Resources::ApiKeys.new(@http, ws_id_proc)
+      @analytics = Resources::Analytics.new(@http)
+      @orders = Resources::Orders.new(@http)
+      @inventory = Resources::Inventory.new(@http)
+      @pickups = Resources::Pickups.new(@http, ws_id_proc)
+      @scan_forms = Resources::ScanForms.new(@http, ws_id_proc)
+      @rules = Resources::Rules.new(@http, ws_id_proc)
+      @offsets = Resources::Offsets.new(@http, ws_id_proc)
+      @hs_codes = Resources::HsCodes.new(@http, ws_id_proc)
+      @recurring_shipments = Resources::RecurringShipments.new(@http, ws_id_proc)
+      @email_templates = Resources::EmailTemplates.new(@http, ws_id_proc)
+      @reports = Resources::Reports.new(@http, ws_id_proc)
+    end
+
+    def set_access_token(token)
+      @http.set_access_token(token)
+    end
+
+    def set_api_key(key)
+      @http.set_api_key(key)
+    end
+  end
+end

data/lib/flexops/errors.rb

@@ -0,0 +1,35 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  class Error < StandardError
+    attr_reader :status, :code, :errors
+
+    def initialize(message, status: 0, code: nil, errors: nil)
+      super(message)
+      @status = status
+      @code = code
+      @errors = errors
+    end
+  end
+
+  class AuthError < Error
+    def initialize(message = "Authentication required. Check your access token or API key.")
+      super(message, status: 401, code: "UNAUTHORIZED")
+    end
+  end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(retry_after: 0)
+      super("Rate limited. Retry after #{retry_after}s", status: 429, code: "RATE_LIMITED")
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/flexops/http.rb

@@ -0,0 +1,173 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+require "net/http"
+require "uri"
+require "json"
+
+module FlexOps
+  class HttpClient
+    DEFAULT_BASE_URL = "https://gateway.flexops.io"
+    DEFAULT_TIMEOUT = 30
+    MAX_RETRIES = 3
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+    def initialize(base_url: DEFAULT_BASE_URL, api_key: nil, access_token: nil, timeout: DEFAULT_TIMEOUT)
+      @base_url = base_url.chomp("/")
+      @api_key = api_key
+      @access_token = access_token
+      @timeout = timeout
+    end
+
+    def set_access_token(token)
+      @access_token = token
+      @api_key = nil
+    end
+
+    def set_api_key(key)
+      @api_key = key
+      @access_token = nil
+    end
+
+    def get(path, query: nil)
+      request(:get, path, query: query)
+    end
+
+    def post(path, body: nil, query: nil)
+      request(:post, path, body: body, query: query)
+    end
+
+    def put(path, body: nil)
+      request(:put, path, body: body)
+    end
+
+    def patch(path, body: nil)
+      request(:patch, path, body: body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def request(method, path, body: nil, query: nil)
+      uri = build_uri(path, query)
+      last_error = nil
+
+      (0..MAX_RETRIES).each do |attempt|
+        if attempt > 0
+          sleep(calculate_backoff(attempt))
+        end
+
+        req = build_request(method, uri, body)
+        begin
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                     open_timeout: @timeout, read_timeout: @timeout) do |http|
+            http.request(req)
+          end
+
+          status = response.code.to_i
+
+          if status >= 200 && status < 300
+            return parse_response(response)
+          end
+
+          if status == 401
+            raise AuthError
+          end
+
+          if status == 403
+            raise Error.new("Access denied. Check your plan tier and feature entitlements.", status: 403, code: "FORBIDDEN")
+          end
+
+          if status == 429
+            retry_after = (response["retry-after"] || "0").to_i
+            last_error = RateLimitError.new(retry_after: retry_after)
+            next if RETRYABLE_STATUSES.include?(429)
+            raise last_error
+          end
+
+          error_body = parse_error_body(response)
+          error = Error.new(
+            error_body["message"] || "HTTP #{status}: #{response.message}",
+            status: status,
+            errors: error_body["errors"]
+          )
+
+          if RETRYABLE_STATUSES.include?(status)
+            last_error = error
+            next
+          end
+
+          raise error
+        rescue Error
+          raise
+        rescue StandardError => e
+          last_error = e
+          next if attempt < MAX_RETRIES
+        end
+      end
+
+      raise last_error || Error.new("Request failed after retries", code: "RETRY_EXHAUSTED")
+    end
+
+    def build_uri(path, query)
+      url = "#{@base_url}#{path.start_with?("/") ? path : "/#{path}"}"
+      uri = URI.parse(url)
+      if query
+        params = URI.encode_www_form(query.compact)
+        uri.query = params unless params.empty?
+      end
+      uri
+    end
+
+    def build_request(method, uri, body)
+      klass = case method
+              when :get    then Net::HTTP::Get
+              when :post   then Net::HTTP::Post
+              when :put    then Net::HTTP::Put
+              when :patch  then Net::HTTP::Patch
+              when :delete then Net::HTTP::Delete
+              end
+
+      req = klass.new(uri)
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+
+      if @api_key
+        req["X-Api-Key"] = @api_key
+      elsif @access_token
+        req["Authorization"] = "Bearer #{@access_token}"
+      end
+
+      req.body = body.to_json if body
+      req
+    end
+
+    def parse_response(response)
+      content_type = response["content-type"] || ""
+      if content_type.include?("application/json")
+        JSON.parse(response.body)
+      else
+        response.body
+      end
+    end
+
+    def parse_error_body(response)
+      JSON.parse(response.body)
+    rescue StandardError
+      {}
+    end
+
+    def calculate_backoff(attempt)
+      jitter = rand(0.85..1.15)
+      [1.0 * (2**(attempt - 1)) * jitter, 30.0].min
+    end
+  end
+end

data/lib/flexops/resources/analytics.rb

@@ -0,0 +1,85 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    class Analytics
+      BASE = "/api/ApiProxy/api/v4/Analytics"
+
+      def initialize(http)
+        @http = http
+      end
+
+      def shipments_trend(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ShipmentsTrend", query: date_query(start_date, end_date))
+      end
+
+      def carrier_summary(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/CarrierSummary", query: date_query(start_date, end_date))
+      end
+
+      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
+
+      def inventory_metrics
+        @http.get("#{BASE}/InventoryMetrics")
+      end
+
+      def stock_by_warehouse
+        @http.get("#{BASE}/StockByWarehouse")
+      end
+
+      def order_metrics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/OrderMetrics", query: date_query(start_date, end_date))
+      end
+
+      def order_trend(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/OrderTrend", query: date_query(start_date, end_date))
+      end
+
+      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
+
+      def returns_metrics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ReturnsMetrics", query: date_query(start_date, end_date))
+      end
+
+      def returns_trend(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ReturnsTrend", query: date_query(start_date, end_date))
+      end
+
+      def return_reasons(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ReturnReasons", query: date_query(start_date, end_date))
+      end
+
+      def performance_metrics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/PerformanceMetrics", query: date_query(start_date, end_date))
+      end
+
+      def carrier_performance(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/CarrierPerformance", query: date_query(start_date, end_date))
+      end
+
+      def shipping_cost_analytics(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/ShippingCostAnalytics", query: date_query(start_date, end_date))
+      end
+
+      def delivery_performance(start_date: nil, end_date: nil)
+        @http.get("#{BASE}/DeliveryPerformance", query: date_query(start_date, end_date))
+      end
+
+      private
+
+      def date_query(start_date, end_date)
+        { startDate: start_date, endDate: end_date }.compact
+      end
+    end
+  end
+end

data/lib/flexops/resources/api_keys.rb

@@ -0,0 +1,40 @@
+# ***********************************************************************
+# 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/auth.rb

@@ -0,0 +1,57 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-03-08
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  module Resources
+    class Auth
+      def initialize(http)
+        @http = http
+      end
+
+      def login(email:, password:)
+        @http.post("/api/Account/login", body: { email: email, password: password })
+      end
+
+      def register(request)
+        @http.post("/api/Account/register", body: request)
+      end
+
+      def refresh_token(refresh_token)
+        @http.post("/api/Account/refresh-token", body: { refreshToken: refresh_token })
+      end
+
+      def logout
+        @http.post("/api/Account/logout")
+      end
+
+      def get_profile
+        @http.get("/api/Account/profile")
+      end
+
+      def update_profile(data)
+        @http.put("/api/Account/profile", body: data)
+      end
+
+      def change_password(current_password:, new_password:)
+        @http.post("/api/Account/change-password", body: { currentPassword: current_password, newPassword: new_password })
+      end
+
+      def forgot_password(email:)
+        @http.post("/api/Account/forgot-password", body: { email: email })
+      end
+
+      def reset_password(token:, new_password:)
+        @http.post("/api/Account/reset-password", body: { token: token, newPassword: new_password })
+      end
+
+      def verify_email(token:)
+        @http.post("/api/Account/verify-email", body: { token: token })
+      end
+    end
+  end
+end