flexops 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae38cf941276d4053203fda4a44fb9ab1adb873d24bba9ec1de7fc634be3e7e2
-  data.tar.gz: 43b602d72cbac545bff0391aa2dee8ea28f73bd7807a6042ec17731fe7943881
+  metadata.gz: 0176ab2f4e6ee84a35449cc7c3cc2b0d13708b62fdef7552013db7cce25bff08
+  data.tar.gz: d6c47bc34a6f23aa44bb799c4a1165c87eab2a592439a8e8a10bd39774f5e6f4
 SHA512:
-  metadata.gz: '0959231eed12a9abd27bc7d370ab9576e32393a131248e231f2d7bebb622c74c29c21596f55036c1af8df73a277a3cbb8ee282c516aca90fc787839c76f102dc'
-  data.tar.gz: 42fa01ac062f0f54ed7632e403a0d3a5ed37e3e942e6f11a45797b047f7f343c3b0419d354e83af9be217d58d1877a322ee7fee7fa6c79e9749e069cfca0f7cf
+  metadata.gz: cf5f9b203dbf64a94243192fd7db18fc131275b0da8ceff6a5165bc88fb64b85e26efb0d71062e030a1acf45cec9e5a3717da17833636ab6685ddc010dcb6b62
+  data.tar.gz: 570d832da16f3449283d3d064197efe2eeba19e6fad36183179490564829a1217f488038bd81970357a67bfef685be2d3dd06b1a3ced0e6eb0ac1272cc48a752

data/README.md

@@ -29,8 +29,8 @@ require "flexops"
 
 # API key authentication (recommended for server-to-server)
 client = FlexOps::Client.new(
-  api_key: "fxk_live_...",
-  workspace_id: "ws_abc123"
+  api_key: "live_...",
+  workspace_id: "your-workspace-id"
 )
 
 # Get shipping rates from all carriers
@@ -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"]
@@ -88,57 +90,220 @@ separate contracts. The SDK never automatically confirms a preview.
 ### API key (recommended)
 
 ```ruby
-client = FlexOps::Client.new(api_key: "fxk_live_...", workspace_id: "ws_abc123")
+client = FlexOps::Client.new(api_key: "live_...", workspace_id: "your-workspace-id")
 ```
 
 ### 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"
+session = client.auth.login(email: "user@example.com", password: "password")
+client.set_access_token(session["data"]["token"])
+client.workspace_id = "your-workspace-id"
 ```
 
 ## 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.
+Use `test_...` (instead of `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")
+client = FlexOps::Client.new(api_key: "test_...", workspace_id: "your-workspace-id")
 ```
 
-## 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 domestic label
-label = client.carriers.usps.create_domestic_label(
-  image_type: "PDF",
-  mail_class: "PRIORITY_MAIL",
-  weight_in_ounces: 16
+# 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
+# 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>")
+```
 
-# FedEx rate quote
-rates = client.carriers.fedex.get_rates(...)
+## Multi-package labels
 
-# UPS tracking
-info = client.carriers.ups.track(tracking_number: "1Z999AA10123456784")
+One order shipped in several boxes with the same carrier and service; each box gets its own label and
+a box that fails does not stop the others. Multi-package labels cannot carry HAZMAT: send
+`FlexOps::HazmatClassification::NONE` or leave `hazmatClassification` out.
 
-# DHL shipment
-shipment = client.carriers.dhl.create_shipment(...)
+```ruby
+begin
+  shipment = client.shipping.create_multi_package(
+    { orderId: 12345, carrierCode: "USPS", serviceCode: "PRIORITY",
+      hazmatClassification: FlexOps::HazmatClassification::NONE,
+      packages: [{ weightInOunces: 16, lengthInInches: 10, widthInInches: 8, heightInInches: 4, packageReference: "Box 1 of 2" },
+                 { weightInOunces: 8, lengthInInches: 6, widthInInches: 6, heightInInches: 6, packageReference: "Box 2 of 2" }] },
+    idempotency_key: "order-12345-boxes" # optional; reuse it when you retry
+  )
+rescue FlexOps::Error => e
+  # No label was bought: 422 AllPackagesFailed, or 409 OutcomeUnknown when a label may exist
+  # (check the order before buying again). e.data holds the per-box results.
+end
 ```
 
-## Webhook verification
+`client.returns.get` reads a received return by its numeric return id; read an RMA with
+`client.returns.get_rma("RMA-1001")` or page through them with `client.returns.list_rmas`.
+
+## Wallet balance
 
 ```ruby
-valid = FlexOps::Resources::Webhooks.verify_signature(
-  payload:   request.body.read,
-  signature: request.headers["X-FlexOps-Signature"],
-  secret:    "whsec_..."
+balance = client.wallet.get_balance # {"hasWallet" => true, "balanceCents" => 1250, "balance" => 12.5}
+```
+
+The request carries `X-Workspace-Id` set to the client's `workspace_id`. Funding and
+transaction history are managed in the FlexOps portal.
+
+## Webhook subscriptions
+
+```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
+# 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:
@@ -146,7 +311,7 @@ Every SDK method is a thin wrapper around the FlexOps REST API. If you want to v
 ```bash
 # Shop rates across all connected carriers
 curl -X POST https://gateway.flexops.io/api/shipping/rates \
-  -H "X-API-Key: fxk_live_..." \
+  -H "X-API-Key: live_..." \
   -H "Content-Type: application/json" \
   -d '{
     "origin": {"addressLine1": "123 Main St", "city": "New York", "stateProvince": "NY", "postalCode": "10001", "countryCode": "US"},
@@ -155,15 +320,17 @@ 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 \
-  -H "X-API-Key: fxk_live_..." \
+# hazmatClassification 0 = not hazardous; required when there is no orderId.
+curl -X POST https://gateway.flexops.io/api/shipping/labels \
+  -H "X-API-Key: live_..." \
   -H "Content-Type: application/json" \
   -d '{
     "carrierCode": "USPS", "serviceCode": "GROUND_ADVANTAGE",
     "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,55 +338,56 @@ 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 \
-  -H "X-API-Key: fxk_live_..."
+curl https://gateway.flexops.io/api/shipping/track/9400111899223456789012 \
+  -H "X-API-Key: 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_..."
+# Cancel a label
+curl -X DELETE "https://gateway.flexops.io/api/shipping/labels/lbl_123?carrierCode=USPS" \
+  -H "X-API-Key: live_..."
 ```
 
-Use an `fxk_test_...` key instead of `fxk_live_...` to hit the sandbox environment; mock carriers respond, no real charges, no real labels.
+Use a `test_...` key instead of `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.auth` | Login, token refresh, logout |
+| `client.workspaces` | List and read workspaces; list, invite and remove members, change roles |
+| `client.shipping` | Rate shopping, labels, multi-package 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 received returns; create, read and list 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
 
 ```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
+  api_key:      "live_...",                # API key auth
+  workspace_id: "your-workspace-id",       # Default workspace
   timeout:      30                         # Request timeout (seconds)
 )
 ```
 
 ## 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

@@ -8,13 +8,16 @@
 
 module FlexOps
   class Error < StandardError
-    attr_reader :status, :code, :errors
+    # data is the envelope's "data" on an error reply, when the Gateway sends one. A
+    # multi-package 422 AllPackagesFailed or 409 OutcomeUnknown carries the per-box results there.
+    attr_reader :status, :code, :errors, :data
 
-    def initialize(message, status: 0, code: nil, errors: nil)
+    def initialize(message, status: 0, code: nil, errors: nil, data: nil)
       super(message)
       @status = status
       @code = code
       @errors = errors
+      @data = data
     end
   end
 
@@ -32,4 +35,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