Merge origin/main (#143 subscriptions, #144 fuel-surcharge) into feat/99-spreads-indicators

Conflicts resolved by keeping every side:
- CHANGELOG.md: #99 spreads/indicators entry, then the #100 and #101
  Added entries and the #100 Fixed entries, all under [Unreleased].
- oilpriceapi/async_client.py: spreads, indicators and fuel_surcharge all
  registered (subscriptions untouched).
- oilpriceapi/async_resources.py: metrics_models import plus main's
  multi-line models import; AsyncFuelSurchargeResource kept whole, followed
  by AsyncSpreadsResource and AsyncIndicatorsResource.

Verified on the merged tree by instantiating both clients: spreads,
indicators, fuel_surcharge and subscriptions and all their methods exist
(88/88). Full suite 1859 passed / 3 failed (known live demo 429s) /
68 skipped; ruff, mypy and storefront validator clean. The .gitignore
fixture exception and all 30 fixtures survive.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015ao5paex73xXvuM424Libo

Author: karlwaldman

CHANGELOG.md

@@ -35,6 +35,61 @@ All notable changes to the OilPriceAPI Python SDK will be documented in this fil
     the first 20 codes.
   - `/v1/indicators/congressional-trades` is deliberately not exposed. It has
     never returned data in production, so there is no response shape to type.
+- **Subscription lifecycle: `get`, `update`, `pause`, `resume` (#100).** Sync
+  and async, against `GET`/`PATCH /v1/subscriptions/{id}` and
+  `POST /v1/subscriptions/{id}/pause|resume`. Each returns a typed
+  `Subscription` with the server's timestamps and nulls as sent. `update()`
+  sends only the fields you pass (`name`, `codes`, `interval`,
+  `deliver_webhook`, `status`). Ids and update payloads are validated before
+  any request is built; an invalid one raises `ValidationError` with
+  `status_code=None`, `field` naming the argument, and nothing sent. Unknown ids raise `DataNotFoundError`; a refused update (interval
+  below the plan minimum, webhook delivery the plan lacks) raises
+  `ValidationError` with the server's `details`. `update`, `pause` and
+  `resume` are writes and are sent once, like `create`: after an ambiguous
+  timeout or 5xx the error carries `ambiguous_write=True` and `get()` tells
+  you whether the change landed.
+- **Typed LTL and parcel fuel-surcharge clients (#101).** `client.fuel_surcharge`
+  on both `OilPriceAPI` and `AsyncOilPriceAPI` covers all six
+  `/v1/fuel-surcharge` routes: `list()`, `latest(carrier)`,
+  `history(carrier, page=, per_page=)`, `parcel_list()`,
+  `parcel_latest(carrier)`, `parcel_latest_rate(carrier, service_level)` and
+  `parcel_history(carrier, service_level, page=, per_page=)`. Responses are
+  `FuelSurchargeRate`, `FuelSurchargeHistoryPage` (with the server's
+  `meta`) and `ParcelFuelSurchargeCarrier` models typed from production
+  payloads captured on 2026-09-13: `effective_date` is a `date`,
+  `retrieved_at` a timezone-aware `datetime`, and `source`, nullable
+  `doe_diesel_price` and `diesel_band` are kept as sent. A success body
+  missing a field the API always sends raises
+  `OilPriceAPIError(code="MALFORMED_RESPONSE")` instead of defaulting it.
+  Carrier slugs, service levels and pagination are validated before any
+  request; out-of-range `page`/`per_page` are refused because the API clamps
+  them silently.
+- **Fuel-surcharge 400/404 bodies populate `error.suggestions`.** The
+  `covered_carriers` and `available_service_levels` lists the API returns with
+  an unknown carrier or a missing service level are now surfaced the same way
+  commodity suggestions are.
+
+### Fixed
+
+- **`subscriptions.create()` no longer turns a malformed success into a
+  half-built record.** It fell back to treating the whole `data` object as the
+  subscription when `data.subscription` was missing, and leaked a raw pydantic
+  or `TypeError` when the record was null or a list. It now raises
+  `OilPriceAPIError(code="MALFORMED_RESPONSE")`, the same as the new lifecycle
+  methods.
+- **`subscriptions.delete()` validates the id before sending.** An id such as
+  `"abc/pause"` or `""` previously produced a request to a different route; it
+  now raises `ValidationError(field="subscription_id", status_code=None)`.
+- **A bad subscription `interval` is now an SDK refusal as well as a
+  `ValueError`.** `subscriptions.create(interval=...)`, `normalize_interval` and
+  `build_create_body` raise the new `SubscriptionIntervalError`, a subclass of
+  both `ValidationError` and `ValueError` (like `FuturesContractError`), so
+  `except OilPriceAPIError` catches it and existing `except ValueError` code
+  keeps working. It carries `field="interval"`, the rejected `value`, and
+  `status_code=None`.
+- **`Subscription.codes` is required.** A record with no `codes` used to
+  default to `[]`, reading as a watch on nothing; the API always sends it, so a
+  missing value now fails validation instead of being invented.
 
 ## [1.15.0] - 2026-09-13
 

README.md

@@ -214,6 +214,33 @@ An empty permit search or production history is a valid data state. Do not
 infer broader well-level coverage from the presence of permit data or an SDK
 helper; dataset and account availability come from the current API response.
 
+## Carrier Fuel Surcharges
+
+Weekly fuel surcharges for LTL carriers and, per service level, for parcel
+carriers. Each rate keeps the carrier's `effective_date` and the `source` URL
+and `retrieved_at` time it was retrieved from; a null the API sends (for
+example `doe_diesel_price` on parcel rates) stays `None`.
+
+```python
+import os
+
+from oilpriceapi import OilPriceAPI
+
+with OilPriceAPI(api_key=os.environ["OILPRICEAPI_KEY"]) as client:
+    odfl = client.fuel_surcharge.latest("odfl")
+    history = client.fuel_surcharge.history("odfl", per_page=10)
+    ups_ground = client.fuel_surcharge.parcel_latest_rate("ups", "ground")
+
+print(odfl.surcharge_percent, odfl.effective_date, odfl.source)
+print(history.meta.total_count, [row.effective_date for row in history.history])
+print(ups_ground.surcharge_percent, ups_ground.service_level)
+```
+
+An unknown or uncovered carrier raises `DataNotFoundError` with the covered
+carriers in `error.suggestions`. `page` must be 1 or more and `per_page` 1 to
+100; the SDK refuses other values rather than letting the API clamp them.
+See [`examples/fuel_surcharge.py`](examples/fuel_surcharge.py).
+
 ## Complete pandas DataFrames
 
 Install the optional pandas support, then request a historical DataFrame:

docs/reference/resources.md

@@ -60,6 +60,10 @@
 
 ::: oilpriceapi.resources.drilling.DrillingIntelligenceResource
 
+## Fuel Surcharges
+
+::: oilpriceapi.resources.fuel_surcharge.FuelSurchargeResource
+
 ## Well Production (Beta)
 
 ::: oilpriceapi.resources.well_production.WellProductionResource
@@ -71,3 +75,11 @@
 ## Data Sources
 
 ::: oilpriceapi.resources.data_sources.DataSourcesResource
+
+## Subscriptions
+
+Agent price watches: `list`, `create`, `get`, `update`, `pause`, `resume`,
+`delete`, and the `events` poll. A subscription here is a watch on commodity
+codes, not a billing subscription.
+
+::: oilpriceapi.resources.subscriptions.SubscriptionsResource

examples/fuel_surcharge.py

@@ -0,0 +1,52 @@
+"""Carrier fuel surcharges: LTL and parcel (#101).
+
+Usage:
+    OILPRICEAPI_KEY=... python examples/fuel_surcharge.py
+
+Prints the latest LTL surcharge per carrier, one carrier's recent weekly
+history, and the latest parcel surcharge per service level. Every row shows the
+carrier's effective date and where the value was retrieved from.
+"""
+
+import os
+
+from oilpriceapi import OilPriceAPI
+from oilpriceapi.exceptions import DataNotFoundError
+
+
+def main() -> None:
+    with OilPriceAPI(api_key=os.environ["OILPRICEAPI_KEY"]) as client:
+        print("LTL carriers")
+        rates = client.fuel_surcharge.list()
+        for rate in rates:
+            print(
+                f"  {rate.carrier:<22} {rate.surcharge_percent:>6.2f}%  "
+                f"effective {rate.effective_date}  retrieved {rate.retrieved_at:%Y-%m-%d}"
+            )
+
+        if rates:
+            carrier = rates[0].carrier
+            page = client.fuel_surcharge.history(carrier, per_page=4)
+            print(f"\n{carrier} history ({page.meta.total_count} weeks on record)")
+            for row in page.history:
+                diesel = "n/a" if row.doe_diesel_price is None else f"${row.doe_diesel_price:.3f}"
+                print(f"  {row.effective_date}  {row.surcharge_percent:.2f}%  DOE diesel {diesel}")
+            print(f"  source: {page.history[0].source}" if page.history else "  no rows")
+
+        print("\nParcel carriers")
+        for parcel in client.fuel_surcharge.parcel_list():
+            for rate in parcel.service_levels:
+                print(
+                    f"  {parcel.carrier:<6} {rate.service_level:<26} "
+                    f"{rate.surcharge_percent:>6.2f}%  effective {rate.effective_date}"
+                )
+
+        try:
+            client.fuel_surcharge.latest("fedex-freight")
+        except DataNotFoundError as error:
+            print(f"\nNot covered: {error.message}")
+            print(f"Covered carriers: {', '.join(error.suggestions)}")
+
+
+if __name__ == "__main__":
+    main()

oilpriceapi/__init__.py

@@ -25,6 +25,7 @@
     PermissionDeniedError,
     RateLimitError,
     ServerError,
+    SubscriptionIntervalError,
     TimeoutError,
     ValidationError,
 )
@@ -33,9 +34,14 @@
     DieselPrice,
     DieselStation,
     DieselStationsResponse,
+    FuelSurchargeDieselBand,
+    FuelSurchargeHistoryMeta,
+    FuelSurchargeHistoryPage,
+    FuelSurchargeRate,
     MarketBrief,
     MarketBriefCommodity,
     MarketBriefForecast,
+    ParcelFuelSurchargeCarrier,
     PriceAlert,
     Subscription,
     SubscriptionEvent,
@@ -63,6 +69,7 @@
     "DataNotFoundError",
     "ServerError",
     "FuturesContractError",
+    "SubscriptionIntervalError",
     "ValidationError",
     "NetworkError",
     "TimeoutError",
@@ -76,6 +83,11 @@
     "MarketBrief",
     "MarketBriefCommodity",
     "MarketBriefForecast",
+    "FuelSurchargeRate",
+    "FuelSurchargeDieselBand",
+    "FuelSurchargeHistoryMeta",
+    "FuelSurchargeHistoryPage",
+    "ParcelFuelSurchargeCarrier",
     "Subscription",
     "SubscriptionEvent",
     "SubscriptionEventsPage",