flexops 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae38cf941276d4053203fda4a44fb9ab1adb873d24bba9ec1de7fc634be3e7e2
-  data.tar.gz: 43b602d72cbac545bff0391aa2dee8ea28f73bd7807a6042ec17731fe7943881
+  metadata.gz: 99bb604e4e35131d7525633fbfad7103b380170556b47250599192256636eec1
+  data.tar.gz: b9fb3ccd224541332bd03fd9e8510937fbed4d093c6ab3443dfd41fee0565229
 SHA512:
-  metadata.gz: '0959231eed12a9abd27bc7d370ab9576e32393a131248e231f2d7bebb622c74c29c21596f55036c1af8df73a277a3cbb8ee282c516aca90fc787839c76f102dc'
-  data.tar.gz: 42fa01ac062f0f54ed7632e403a0d3a5ed37e3e942e6f11a45797b047f7f343c3b0419d354e83af9be217d58d1877a322ee7fee7fa6c79e9749e069cfca0f7cf
+  metadata.gz: 12823e90e21cd1eeefcf883ab5c7ed9a4e9d008b2e26bd80ac6014a05e3b6e6b57e4054a3757574173886b2c8ed6a08e6c8d3a2863f6034eb592e6e8d03da5c1
+  data.tar.gz: fb7a48fb211dfb1af4ddd9a0be588eb58318b8ffd445578a09dcacdef625ff9dc8e3dbc593b59a21da18acf678d67d9ca0bd76aef55a22843be9748bfddcf5fa

data/README.md

@@ -45,7 +45,9 @@ request = {
   origin: {name: "Warehouse", addressLine1: "123 Main St", city: "New York", stateProvince: "NY", postalCode: "10001", countryCode: "US"},
   destination: {name: "Customer", addressLine1: "456 Oak Ave", city: "Los Angeles", stateProvince: "CA", postalCode: "90210", countryCode: "US"},
   package: {weight: 16, weightUnit: "oz"},
-  maximumPostageAmount: 10.25 # Caller-approved ceiling in USD.
+  maximumPostageAmount: 10.25, # Caller-approved ceiling in USD.
+  # Required without an orderId. The SDK never fills it in; NONE (0) = not hazardous.
+  hazmatClassification: FlexOps::HazmatClassification::NONE
 }
 preview = client.shipping.create_label(request)
 puts preview["quotedPostageAmount"]
@@ -95,7 +97,8 @@ client = FlexOps::Client.new(api_key: "fxk_live_...", workspace_id: "ws_abc123")
 
 ```ruby
 client = FlexOps::Client.new(base_url: "https://gateway.flexops.io")
-client.auth.login(email: "user@example.com", password: "password")
+session = client.auth.login(email: "user@example.com", password: "password")
+client.set_access_token(session["data"]["token"])
 client.workspace_id = "ws_abc123"
 ```
 
@@ -107,38 +110,176 @@ Use `fxk_test_...` (instead of `fxk_live_...`) to route to the sandbox environme
 client = FlexOps::Client.new(api_key: "fxk_test_...", workspace_id: "ws_abc123")
 ```
 
-## Direct carrier operations
+## Carrier-specific calls
 
-Access carrier-specific endpoints when you need full control:
+`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.
+- 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
+  the proxy is retired.
+- Label generation through the proxy is closed (410 Gone), so the SDK has no carrier label
+  method.
+
+Use the native routes instead where they cover the call:
+
+| Instead of | Use |
+|---|---|
+| Carrier rate calls | `client.shipping.get_rates` |
+| Carrier labels | `client.shipping.create_label` (`client.returns.generate_label` for returns) |
+| Label cancels | `client.shipping.cancel_label` |
+| Carrier pickups | `client.pickups.schedule`, `list`, `get`, `cancel` |
+| USPS scan forms | `client.scan_forms.create` |
+| Address validation | `client.shipping.validate_address` |
+| Tracking | `client.shipping.track` |
+
+```ruby
+# USPS city and state for a ZIP code (works with an API key)
+place = client.carriers.usps.city_state_lookup("10001")
+```
+
+## Retries and idempotency
+
+The client retries a request up to three times with exponential backoff:
+
+- GET: after a dropped connection or timeout, and on 429, 500, 502, 503 and 504.
+- POST, PUT and PATCH: after a dropped connection or timeout, and on 429, 502, 503, 504 and
+  409 `IDEMPOTENCY_CONFLICT` (the first request with that key is still running). Never on 500:
+  the Gateway does not replay a 5xx, so a retry could run the write (and charge the wallet)
+  again.
+- DELETE: only on 429.
+
+A key reused with a different request body gets 422 `IDEMPOTENCY_KEY_REUSED`; it is not retried
+and raises `FlexOps::Error` with that `code`. Error codes are matched exactly, so a label
+purchase's own 409 `IdempotencyConflict` (altered inputs under a used key) is not retried either.
+
+Every POST, PUT and PATCH carries an `Idempotency-Key` header. Pass your own to
+`shipping.create_label(request, idempotency_key: ...)`, `insurance.purchase(..., idempotency_key: ...)`
+or `carbon_offsets.purchase(..., idempotency_key: ...)`, and store it so a retry your app makes after
+an error or a timeout reuses it; otherwise the client generates one UUID
+per call and sends it on every retry of that call, so the Gateway replays a write it already
+finished instead of running it twice. A 2xx response with no body returns `nil`.
+
+## Workspace members
+
+Roles are the Gateway `WorkspaceRole` numbers (Owner 0, Admin 1, Member 2, Merchant 3). Pass a
+`FlexOps::WorkspaceRole` constant or a name; the SDK sends the number.
+
+```ruby
+client.workspaces.invite_member(email: "ops@example.com", role: :member)
+client.workspaces.update_member_role(user_id, FlexOps::WorkspaceRole::ADMIN)
+
+result = client.workspaces.list_members
+members = result["data"]["members"] # also "pendingInvites", "userLimit", "canInviteMore"
+```
+
+## Recurring shipments, report schedules and email templates
+
+Reads work with any API key or a user token. Writes (every POST, PUT and DELETE, including the
+email template preview) need a user token from `auth.login` or an API key granted the
+resource's opt-in scope: `recurring-shipments:write`, `report-schedules:write` or
+`email-templates:write`. Older keys do not have these scopes; a key without one gets 403
+`API_KEY_SCOPE_REQUIRED` with `requiredScopes`. Enums are sent as numbers and ids are GUID
+strings.
 
 ```ruby
-# USPS domestic label
-label = client.carriers.usps.create_domestic_label(
-  image_type: "PDF",
-  mail_class: "PRIORITY_MAIL",
-  weight_in_ounces: 16
+# Recurring shipments (bare JSON). interval: Daily 0, Weekly 1, Biweekly 2, Monthly 3, Custom 4
+schedule = client.recurring_shipments.create(
+  name: "Weekly restock", addressId: address_id, presetId: preset_id,
+  interval: 1, firstRunUtc: "2026-11-02T14:00:00Z"
 )
+client.recurring_shipments.pause(schedule["id"])  # nil (204); also resume, delete
+client.recurring_shipments.trigger(schedule["id"], idempotency_key: run_key) # creates an order now
+
+# Report schedules ({ success, data, message } envelope).
+# format: Csv 0, Json 1; frequencyType: Daily 0, Weekly 1, Monthly 2
+report = client.report_schedules.create(
+  reportType: "shipments", format: 0, frequencyType: 1, dayOfWeek: 1,
+  timeOfDayUtc: "08:00:00", recipientEmails: "ops@example.com"
+)["data"]
+client.report_schedules.toggle(report["id"]) # flips isEnabled
+
+# Tracking email templates (bare JSON), one per event. eventType: LabelCreated 0, InTransit 1,
+# OutForDelivery 2, Delivered 3, Exception 4, ReturnToSender 5
+client.email_templates.upsert(eventType: 3, subjectTemplate: "Delivered: {{tracking_number}}",
+                              htmlBodyTemplate: "<p>Your package arrived.</p>")
+client.email_templates.preview(subject_template: "Hi {{recipient_name}}", html_body_template: "<p>{{status}}</p>")
+```
+
+## Wallet balance
+
+```ruby
+balance = client.wallet.get_balance # {"hasWallet" => true, "balanceCents" => 1250, "balance" => 12.5}
+```
 
-# FedEx rate quote
-rates = client.carriers.fedex.get_rates(...)
+The request carries `X-Workspace-Id` set to the client's `workspace_id`. Funding and
+transaction history are managed in the FlexOps portal.
 
-# UPS tracking
-info = client.carriers.ups.track(tracking_number: "1Z999AA10123456784")
+## Webhook subscriptions
 
-# DHL shipment
-shipment = client.carriers.dhl.create_shipment(...)
+```ruby
+# Leave events out to receive every event.
+webhook = client.webhooks.create(
+  url: "https://your-app.com/webhooks/flexops",
+  events: [FlexOps::WebhookEventType::LABEL_CREATED,
+           FlexOps::WebhookEventType::LABEL_CANCELED,
+           FlexOps::WebhookEventType::BATCH_COMPLETED]
+)
+signing_secret = webhook["secret"] # "whsec_...", returned only on create; store it
+
+# Change the events (or url, description, status: "Active", "Paused", "Disabled").
+client.webhooks.update(webhook["id"], events: [FlexOps::WebhookEventType::LABEL_CREATED])
 ```
 
+`create` returns the subscription itself (`"id"`, `"url"`, `"eventTypes"`, `"status"`, `"secret"`, ...), because the Gateway answers it with the bare subscription. The other webhook methods return the usual `{"success" => true, "data" => ...}` envelope.
+
+`events` is sent as the Gateway's comma-separated `eventTypes`. FlexOps sends these events, named exactly as below (`FlexOps::WebhookEventType::ALL` lists them). Names are PascalCase and matched exactly, so a name like `label.created` would never match; `create` and `update` raise `ArgumentError`, before any request, for an unknown name, an empty list or a non-array.
+
+| Event | Sent when |
+|---|---|
+| `LabelCreated` | A live label is purchased (sandbox labels send nothing) |
+| `LabelCanceled` | A live label is voided |
+| `BatchCompleted` | A batch label job finishes |
+| `TrackingUpdated` | A USPS tracking scan arrives (USPS push-tracking pilot workspaces only) |
+| `TrackingDelivered` | A USPS package is delivered (USPS push-tracking pilot workspaces only) |
+
+You can send a raw `eventTypes:` string (`"*"` or names joined by commas with no spaces) instead of `events:`; it is passed through unchecked, for example to subscribe to an event newer than your SDK version.
+
 ## Webhook verification
 
+FlexOps signs each delivery with HMAC-SHA256 over `{X-FlexOps-Timestamp}.{raw body}`, keyed with your subscription secret (`whsec_...`, used as-is), and sends it as `X-FlexOps-Signature: sha256=<hex>`. Verify the raw body before you parse it.
+
 ```ruby
-valid = FlexOps::Resources::Webhooks.verify_signature(
-  payload:   request.body.read,
-  signature: request.headers["X-FlexOps-Signature"],
-  secret:    "whsec_..."
-)
+# Rails controller action
+def flexops_webhook
+  payload = request.raw_post
+
+  valid = FlexOps::Resources::Webhooks.verify_signature(
+    payload:   payload,
+    signature: request.headers["X-FlexOps-Signature"], # "sha256=..."
+    timestamp: request.headers["X-FlexOps-Timestamp"], # Unix seconds
+    secret:    ENV.fetch("FLEXOPS_WEBHOOK_SECRET")      # "whsec_..."
+  )
+  return head :unauthorized unless valid
+
+  # The body is the event data itself (no type/data envelope).
+  # The event name is in a header; test events send "test".
+  data = JSON.parse(payload)
+  case request.headers["X-FlexOps-Event"]
+  when "test"
+    # data: {"type"=>"test", "message"=>"...", "timestamp"=>"...", "subscriptionId"=>"..."}
+  when "TrackingUpdated"
+    # data["trackingNumber"], data["status"], ...
+  end
+  head :ok
+end
 ```
 
+Deliveries whose timestamp is more than 300 seconds from your clock (either way) are rejected to limit replays; pass `tolerance:` (seconds) to change that. `verify_signature!` takes the same arguments and raises `FlexOps::WebhookSignatureError` instead of returning `false`; its `code` says why (`WEBHOOK_SIGNATURE_MISMATCH`, `WEBHOOK_TIMESTAMP_OUTSIDE_TOLERANCE`, `WEBHOOK_INVALID_TIMESTAMP`, `WEBHOOK_MISSING_SIGNATURE`, `WEBHOOK_MISSING_SECRET`).
+
 ## 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:
@@ -155,7 +296,8 @@ curl -X POST https://gateway.flexops.io/api/shipping/rates \
   }'
 
 # Preview a live label; this does not purchase it.
-curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/labels \
+# hazmatClassification 0 = not hazardous; required when there is no orderId.
+curl -X POST https://gateway.flexops.io/api/shipping/labels \
   -H "X-API-Key: fxk_live_..." \
   -H "Content-Type: application/json" \
   -d '{
@@ -163,7 +305,8 @@ curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/labels
     "origin": {"name": "Warehouse", "addressLine1": "123 Main St", "city": "New York", "stateProvince": "NY", "postalCode": "10001", "countryCode": "US"},
     "destination": {"name": "Customer", "addressLine1": "456 Oak Ave", "city": "Los Angeles", "stateProvince": "CA", "postalCode": "90210", "countryCode": "US"},
     "package": {"weight": 16, "weightUnit": "oz"},
-    "maximumPostageAmount": 10.25
+    "maximumPostageAmount": 10.25,
+    "hazmatClassification": 0
   }'
 
 # After explicit approval, resend the same body with confirmationToken from
@@ -171,11 +314,11 @@ curl -X POST https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/labels
 # See the SDK example above; retain that key for retries.
 
 # Track a shipment
-curl https://gateway.flexops.io/api/workspaces/ws_abc123/shipping/track/9400111899223456789012 \
+curl https://gateway.flexops.io/api/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 \
+# Cancel a label
+curl -X DELETE "https://gateway.flexops.io/api/shipping/labels/lbl_123?carrierCode=USPS" \
   -H "X-API-Key: fxk_live_..."
 ```
 
@@ -185,26 +328,27 @@ Use an `fxk_test_...` key instead of `fxk_live_...` to hit the sandbox environme
 
 | 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.auth` | Login, token refresh, logout |
+| `client.workspaces` | List and read workspaces; list, invite and remove members, change roles |
+| `client.shipping` | Rate shopping, labels, tracking, address validation, batch, cancel |
+| `client.carriers` | USPS, UPS, FedEx and DHL calls through the legacy proxy; writes are deprecated and need a user token |
+| `client.webhooks` | Subscription create/update/delete, secret rotation, test events, delivery logs, signature verification |
+| `client.wallet` | Workspace balance |
+| `client.insurance` | Providers, quotes, policies, void, claims |
+| `client.returns` | List and read returns; create 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.pickups` | Schedule, list, read and cancel carrier pickups |
 | `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 |
+| `client.rules` | Shipping rules: create, read, update, delete, reorder, test |
+| `client.hs_codes` | HS code search and lookup, landed cost |
+| `client.carbon_offsets` | Carbon offset quotes, purchases, summary and settings |
+| `client.recurring_shipments` | Recurring shipment schedules: create, update, pause, resume, trigger, delete |
+| `client.report_schedules` | Scheduled report emails: create, update, toggle, delete |
+| `client.email_templates` | Tracking email templates: upsert, preview, delete |
+
+API keys, workspace settings and account management are managed in the FlexOps portals.
 
 ## Configuration
 
@@ -219,7 +363,7 @@ client = FlexOps::Client.new(
 
 ## Requirements
 
-- Ruby 3.0+
+- Ruby 3.1+
 
 ## License
 

data/lib/flexops/client.rb

@@ -10,9 +10,9 @@ 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
+                :insurance, :returns, :analytics, :orders, :inventory,
+                :pickups, :scan_forms, :rules, :hs_codes, :carbon_offsets,
+                :recurring_shipments, :report_schedules, :email_templates
 
     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)
@@ -28,18 +28,17 @@ module FlexOps
       @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)
+      @hs_codes = Resources::HsCodes.new(@http)
+      @carbon_offsets = Resources::CarbonOffsets.new(@http, ws_id_proc)
       @recurring_shipments = Resources::RecurringShipments.new(@http, ws_id_proc)
+      @report_schedules = Resources::ReportSchedules.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)

data/lib/flexops/errors.rb

@@ -32,4 +32,13 @@ module FlexOps
       @retry_after = retry_after
     end
   end
+
+  # Raised by Resources::Webhooks.verify_signature! when a webhook delivery
+  # is not authentic or not fresh. +code+ says why, for example
+  # "WEBHOOK_SIGNATURE_MISMATCH" or "WEBHOOK_TIMESTAMP_OUTSIDE_TOLERANCE".
+  class WebhookSignatureError < Error
+    def initialize(message, code:)
+      super(message, code: code)
+    end
+  end
 end

data/lib/flexops/hazmat_classification.rb

@@ -0,0 +1,34 @@
+# ***********************************************************************
+# Package          : flexops
+# Author           : FlexOps, LLC
+# Created          : 2026-10-12
+#
+# Copyright (c) 2021-2026 by FlexOps, LLC. All rights reserved.
+# ***********************************************************************
+
+module FlexOps
+  # USPS HAZMAT classification, sent as the Gateway HazmatClassification number.
+  #
+  # There is no default: leave hazmatClassification out when you have no answer, or send
+  # HazmatClassification::NONE (0) to declare that the parcel holds no dangerous goods.
+  # A label without an orderId must declare one.
+  module HazmatClassification
+    NONE = 0
+    LIMITED_QUANTITY = 1
+    LITHIUM_BATTERY_CONTAINED_IN_EQUIPMENT = 2
+    LITHIUM_BATTERY_PACKED_WITH_EQUIPMENT = 3
+    LITHIUM_BATTERY_STANDALONE = 4
+    OTHER_RESTRICTED = 5
+    LITHIUM_BATTERY_USED_DEVICE = 6
+
+    ALL = {
+      NONE: NONE,
+      LIMITED_QUANTITY: LIMITED_QUANTITY,
+      LITHIUM_BATTERY_CONTAINED_IN_EQUIPMENT: LITHIUM_BATTERY_CONTAINED_IN_EQUIPMENT,
+      LITHIUM_BATTERY_PACKED_WITH_EQUIPMENT: LITHIUM_BATTERY_PACKED_WITH_EQUIPMENT,
+      LITHIUM_BATTERY_STANDALONE: LITHIUM_BATTERY_STANDALONE,
+      OTHER_RESTRICTED: OTHER_RESTRICTED,
+      LITHIUM_BATTERY_USED_DEVICE: LITHIUM_BATTERY_USED_DEVICE
+    }.freeze
+  end
+end

data/lib/flexops/http.rb

@@ -9,13 +9,24 @@
 require "net/http"
 require "uri"
 require "json"
+require "securerandom"
 
 module FlexOps
   class HttpClient
     DEFAULT_BASE_URL = "https://gateway.flexops.io"
     DEFAULT_TIMEOUT = 30
     MAX_RETRIES = 3
+    # Statuses a GET is retried on.
     RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    # Statuses where a keyed write either never ran or is replayed by the Gateway. Never 500:
+    # the Gateway does not cache a 5xx response, so a retry would run the write again.
+    WRITE_RETRYABLE_STATUSES = [429, 502, 503, 504].freeze
+    WRITE_METHODS = %i[post put patch].freeze
+    IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+    # The Gateway's 409 while the first request with the same Idempotency-Key is still running.
+    IDEMPOTENCY_CONFLICT = "IDEMPOTENCY_CONFLICT"
+
+    attr_reader :access_token
 
     def initialize(base_url: DEFAULT_BASE_URL, api_key: nil, access_token: nil, timeout: DEFAULT_TIMEOUT)
       @base_url = base_url.chomp("/")
@@ -34,30 +45,33 @@ module FlexOps
       @access_token = nil
     end
 
-    def get(path, query: nil)
-      request(:get, path, query: query)
+    def get(path, query: nil, headers: {})
+      request(:get, path, query: query, headers: headers)
     end
 
     def post(path, body: nil, query: nil, headers: {})
       request(:post, path, body: body, query: query, headers: headers)
     end
 
-    def put(path, body: nil)
-      request(:put, path, body: body)
+    def put(path, body: nil, headers: {})
+      request(:put, path, body: body, headers: headers)
     end
 
-    def patch(path, body: nil)
-      request(:patch, path, body: body)
+    def patch(path, body: nil, headers: {})
+      request(:patch, path, body: body, headers: headers)
     end
 
-    def delete(path)
-      request(:delete, path)
+    def delete(path, headers: {})
+      request(:delete, path, headers: headers)
     end
 
     private
 
     def request(method, path, body: nil, query: nil, headers: {})
       uri = build_uri(path, query)
+      # Every write carries one key for all of its attempts, so the Gateway replays a write it
+      # already finished instead of running it (and charging the wallet) again.
+      headers = with_idempotency_key(method, headers)
       last_error = nil
 
       (0..MAX_RETRIES).each do |attempt|
@@ -72,53 +86,65 @@ module FlexOps
                                      open_timeout: @timeout, read_timeout: @timeout) do |http|
             http.request(req)
           end
+        rescue StandardError => e
+          # The Gateway may have run a timed-out or dropped request. GETs and keyed writes are
+          # safe to send again; a DELETE is not covered by the idempotency middleware.
+          raise if method == :delete
 
-          status = response.code.to_i
+          last_error = e
+          next
+        end
 
-          if status >= 200 && status < 300
-            return parse_response(response)
-          end
+        status = response.code.to_i
 
-          if status == 401
-            raise AuthError
-          end
+        if status >= 200 && status < 300
+          return parse_response(response)
+        end
 
-          if status == 403
-            raise Error.new("Access denied. Check your plan tier and feature entitlements.", status: 403, code: "FORBIDDEN")
-          end
+        if status == 401
+          raise AuthError
+        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
+        # Rate limited: the request was refused before it ran, so every method retries.
+        if status == 429
+          retry_after = (response["retry-after"] || "0").to_i
+          last_error = RateLimitError.new(retry_after: retry_after)
+          next
+        end
 
-          error_body = parse_error_body(response)
-          error = Error.new(
-            error_body["message"] || "HTTP #{status}: #{response.message}",
-            status: status,
-            code: error_body["errorCode"] || error_body["code"],
-            errors: error_body["errors"]
-          )
-
-          if RETRYABLE_STATUSES.include?(status)
-            last_error = error
-            next
-          end
+        error_body = parse_error_body(response)
+        error = Error.new(
+          error_body["message"] || "HTTP #{status}: #{response.message}",
+          status: status,
+          code: error_body["errorCode"] || error_body["code"] || (status == 403 ? "FORBIDDEN" : nil),
+          errors: error_body["errors"]
+        )
 
-          raise error
-        rescue Error
-          raise
-        rescue StandardError => e
-          last_error = e
-          next if attempt < MAX_RETRIES
-        end
+        raise error unless retryable?(method, status, error.code)
+
+        last_error = error
       end
 
       raise last_error || Error.new("Request failed after retries", code: "RETRY_EXHAUSTED")
     end
 
+    # GETs retry on every RETRYABLE_STATUSES status. A write retries only where the Gateway either
+    # did not run it or will replay it for the same Idempotency-Key. A DELETE retries only on 429.
+    def retryable?(method, status, code)
+      case method
+      when :get then RETRYABLE_STATUSES.include?(status)
+      when :delete then false
+      else status == 409 ? code == IDEMPOTENCY_CONFLICT : WRITE_RETRYABLE_STATUSES.include?(status)
+      end
+    end
+
+    def with_idempotency_key(method, headers)
+      return headers unless WRITE_METHODS.include?(method)
+
+      given = headers.any? { |name, value| name.to_s.casecmp?(IDEMPOTENCY_KEY_HEADER) && !value.to_s.empty? }
+      given ? headers : headers.merge(IDEMPOTENCY_KEY_HEADER => SecureRandom.uuid)
+    end
+
     def build_uri(path, query)
       url = "#{@base_url}#{path.start_with?("/") ? path : "/#{path}"}"
       uri = URI.parse(url)
@@ -152,7 +178,11 @@ module FlexOps
       req
     end
 
+    # A 2xx with no body (204, or Content-Length 0) returns nil; JSON is parsed; anything else,
+    # such as a label file, is returned as the raw body string.
     def parse_response(response)
+      return nil if response.code.to_i == 204 || response["content-length"] == "0" || response.body.nil? || response.body.empty?
+
       content_type = response["content-type"] || ""
       if content_type.include?("application/json")
         JSON.parse(response.body)
@@ -162,7 +192,8 @@ module FlexOps
     end
 
     def parse_error_body(response)
-      JSON.parse(response.body)
+      parsed = JSON.parse(response.body)
+      parsed.is_a?(Hash) ? parsed : {}
     rescue StandardError
       {}
     end

data/lib/flexops/resources/auth.rb

@@ -8,6 +8,8 @@
 
 module FlexOps
   module Resources
+    # Token acquisition for operations that need a signed-in user. Account management
+    # (registration, profile, passwords) belongs to the FlexOps portals.
     class Auth
       def initialize(http)
         @http = http
@@ -17,41 +19,18 @@ module FlexOps
         @http.post("/api/Account/login", body: { email: email, password: password })
       end
 
-      def register(request)
-        @http.post("/api/Account/register", body: request)
-      end
+      # The Gateway RefreshTokenRequest requires the expired access token as well as the refresh
+      # token; it defaults to the client's current access token.
+      def refresh_token(refresh_token, access_token: nil)
+        token = access_token || @http.access_token
+        raise ArgumentError, "access_token is required to refresh a session" if token.to_s.empty?
 
-      def refresh_token(refresh_token)
-        @http.post("/api/Account/refresh-token", body: { refreshToken: refresh_token })
+        @http.post("/api/Account/refresh-token", body: { token: token, 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