feat: validate dates and guide commodity codes (#76)

Author: karlwaldman

CHANGELOG.md

@@ -7,8 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add sync and async `client.commodities.search(...)`, backed by the current
+  API catalog rather than a bundled commodity-code list.
+- Expose bounded, credential-redacted `suggestions` and `invalid_codes` from
+  nested invalid-code error responses.
+
 ### Changed
 
+- Date-bearing resources now reject malformed or impossible `YYYY-MM-DD`
+  strings locally while leaving well-formed range semantics to the API.
 - Historical DataFrame helpers now accept a `per_page` value from 1 to 1000
   and fetch all pages automatically. The `client.prices.to_dataframe(...)`
   convenience path forwards the same option for date-range queries.

README.md

@@ -162,6 +162,24 @@ The same `per_page` behavior applies to date-range queries through
 [DataFrames and pagination guide](docs/DATAFRAMES.md) for the complete
 contract.
 
+## Dates and Commodity Codes
+
+Date strings must be real calendar dates in exact `YYYY-MM-DD` form. Malformed
+values are rejected before an API request, while well-formed ranges are still
+validated authoritatively by the server.
+
+Search the current API catalog instead of maintaining a local code list:
+
+```python
+matches = client.commodities.search("brent crude", limit=5)
+print([commodity["code"] for commodity in matches])
+```
+
+Invalid-code API responses expose sanitized recovery values through
+`error.suggestions` and `error.invalid_codes`. See the
+[dates and commodity-code guide](docs/CODE_GUIDANCE.md) for sync/async examples
+and failure behavior.
+
 ## Recovery
 
 The package exposes typed errors for the customer-recoverable boundaries:
@@ -199,10 +217,10 @@ except OilPriceAPIError as error:
 
 All non-2xx responses share the same `OilPriceAPIError` attributes, including
 `status_code`, `code`, `request_id`, plan/feature recovery fields, retry
-metadata, sanitized response `headers`, `raw_body`, and `raw_text`. Canonical
-nested and legacy flat API error envelopes are normalized into that contract.
-Transport failures use `NetworkError`; timeouts remain the more specific
-`TimeoutError`.
+metadata, commodity `suggestions` and `invalid_codes`, sanitized response
+`headers`, `raw_body`, and `raw_text`. Canonical nested, fail/data, and legacy
+flat API error envelopes are normalized into that contract. Transport failures
+use `NetworkError`; timeouts remain the more specific `TimeoutError`.
 
 Executable recovery examples cover 401, 403, 429, and timeout responses under
 [`examples/snippets/`](examples/snippets/). Empty or malformed successful

docs/CODE_GUIDANCE.md

@@ -0,0 +1,69 @@
+# Dates and commodity-code guidance
+
+## Strict date syntax
+
+SDK methods that accept dates validate each supplied value before sending a
+request. Strings must be a real calendar date in exact `YYYY-MM-DD` form.
+`datetime.date` and `datetime.datetime` values are also accepted and normalized
+to that form.
+
+```python
+from datetime import date
+
+client.historical.get(
+    "BRENT_CRUDE_USD",
+    start_date=date(2026, 1, 1),
+    end_date="2026-01-31",
+)
+```
+
+Malformed values such as `2026-01-010`, `2026-1-10`, impossible calendar
+dates, empty strings, and datetime strings are rejected locally with
+`ValueError`; no API request is made. A range whose individual dates are valid
+but whose ordering or business meaning is invalid is still sent to the API so
+the server remains the authority for range semantics.
+
+## Search the current catalog
+
+Use `commodities.search()` when a code is unknown. Each search fetches the
+current API catalog and ranks matches across code, name, category, description,
+currency, unit, and source. The SDK does not bundle a hand-maintained code list.
+
+```python
+matches = client.commodities.search("brent crude", limit=5)
+for commodity in matches:
+    print(commodity["code"], commodity.get("name"))
+```
+
+The async client provides the same behavior:
+
+```python
+matches = await client.commodities.search("natural gas")
+```
+
+No match or an empty catalog returns `[]`. Authentication, network, timeout,
+and other API failures are not converted into an empty result; their existing
+typed SDK exceptions propagate so callers can distinguish failure from “no
+matches.”
+
+## Recover from an invalid code
+
+When the API includes commodity suggestions in an error response, the SDK
+exposes bounded string values on `error.suggestions`. Invalid submitted codes
+are available on `error.invalid_codes`.
+
+```python
+from oilpriceapi import OilPriceAPIError
+
+try:
+    client.prices.get("BRENNT")
+except OilPriceAPIError as error:
+    if error.code == "invalid_code" and error.suggestions:
+        print("Try one of:", ", ".join(error.suggestions))
+    else:
+        raise
+```
+
+The response parser ignores unexpected non-string suggestion values, limits
+the number and length of values retained, and applies the same credential
+redaction used for other error diagnostics.

docs/index.md

@@ -53,7 +53,7 @@ prices = client.prices.get_multiple([
 
 ### Historical Data
 
-Access years of historical price data for backtesting and analysis:
+Access years of historical price data for backtesting and analysis:
 
 ```python
 # Get historical data
@@ -76,6 +76,10 @@ controls request size rather than total results. See
 boundary behavior.
 
 **[Learn about historical endpoints →](https://docs.oilpriceapi.com/api-reference/historical)**
+
+Date strings use strict `YYYY-MM-DD` syntax and are checked before a request.
+See **[Dates and commodity codes →](CODE_GUIDANCE.md)** for validation and
+recovery behavior.
 
 ### Technical Analysis
 
@@ -134,24 +138,17 @@ Embed live commodity price widgets and charts in your applications.
 
 **[Explore integration guides →](https://docs.oilpriceapi.com/integrations)**
 
-## 📊 Available Commodities
-
-### Crude Oil
-- **Brent Crude** (`BRENT_CRUDE_USD`) - International benchmark
-- **WTI** (`WTI_USD`) - US benchmark
-- **Dubai Crude** (`DUBAI_CRUDE_USD`) - Middle East benchmark
-
-### Natural Gas
-- **Natural Gas** (`NATURAL_GAS_USD`) - Henry Hub spot price
-- **LNG** (`LNG_USD`) - Liquefied natural gas
-
-### Refined Products
-- **Diesel** (`DIESEL_USD`)
-- **Gasoline** (`GASOLINE_USD`)
-- **Heating Oil** (`HEATING_OIL_USD`)
-- **Jet Fuel** (`JET_FUEL_USD`)
-
-**[View complete commodity list →](https://docs.oilpriceapi.com/commodities)**
+## 📊 Find Commodity Codes
+
+Search the current API catalog so an integration does not depend on a stale
+code list:
+
+```python
+matches = client.commodities.search("brent crude", limit=5)
+print([commodity["code"] for commodity in matches])
+```
+
+**[View dates and commodity-code guidance →](CODE_GUIDANCE.md)**
 
 ## 🔧 Advanced Configuration
 
@@ -202,6 +199,8 @@ except RateLimitError as error:
 except DataNotFoundError:
     print("Commodity not found")
 except OilPriceAPIError as error:
+    if error.code == "invalid_code" and error.suggestions:
+        print("Try one of:", ", ".join(error.suggestions))
     if error.request_id:
         print("Support request ID:", error.request_id)
     if error.remediation_url:
@@ -210,8 +209,9 @@ except OilPriceAPIError as error:
 ```
 
 Every non-2xx response uses this shared typed contract. `status_code`, `code`,
-plan or feature requirements, retry metadata, sanitized response headers, and
-raw diagnostics remain available without exposing the configured API key.
+commodity suggestions, plan or feature requirements, retry metadata, sanitized
+response headers, and raw diagnostics remain available without exposing the
+configured API key.
 
 ## 💰 Pricing & Plans
 

mkdocs.yml

@@ -15,6 +15,7 @@ theme:
 
 nav:
   - Home: index.md
+  - Dates and Commodity Codes: CODE_GUIDANCE.md
   - DataFrames and Pagination: DATAFRAMES.md
   - Synthetic Monitoring: SYNTHETIC_MONITORING.md
   - Release Process: RELEASE_PROCESS.md

oilpriceapi/async_client.py

@@ -42,6 +42,7 @@
     error_from_response,
 )
 from .models import HistoricalPrice, HistoricalResponse, MarketBrief, Price
+from .resource_validators import format_date
 from .retry import RetryStrategy
 
 
@@ -464,10 +465,10 @@ async def get(
             "by_type": type_name,
         }
 
-        if start_date:
-            params["start_date"] = start_date
-        if end_date:
-            params["end_date"] = end_date
+        if start_date is not None:
+            params["start_date"] = format_date(start_date)
+        if end_date is not None:
+            params["end_date"] = format_date(end_date)
 
         response = await self.client.request(
             method="GET", path="/v1/prices/past_year", params=params

oilpriceapi/async_resources.py

@@ -10,7 +10,13 @@
 )
 from .exceptions import ValidationError
 from .models import DieselPrice, DieselStationsResponse, PriceAlert, Subscription, SubscriptionEvent
-from .resource_validators import VALID_OPERATORS, format_date, normalize_api_number
+from .resource_validators import (
+    VALID_OPERATORS,
+    extract_commodity_catalog,
+    format_date,
+    normalize_api_number,
+    search_commodity_catalog,
+)
 from .resources._futures_slug import normalize_futures_slug
 from .resources.subscriptions import SubscriptionEventsPage
 
@@ -286,16 +292,19 @@ def __init__(self, client):
 
     async def list(self) -> List[Dict[str, Any]]:
         response = await self.client.request(method="GET", path="/v1/commodities")
-        if "data" in response:
-            return response["data"]
-        return response
+        return extract_commodity_catalog(response)
 
     async def get(self, code: str) -> Dict[str, Any]:
         response = await self.client.request(method="GET", path=f"/v1/commodities/{code}")
         if "data" in response:
             return response["data"]
         return response
 
+    async def search(self, query: str, limit: int = 10) -> List[Dict[str, Any]]:
+        """Search the API's current catalog without a bundled code list."""
+        catalog = await self.list()
+        return search_commodity_catalog(catalog, query=query, limit=limit)
+
     async def categories(self) -> Dict[str, List[Dict[str, Any]]]:
         response = await self.client.request(method="GET", path="/v1/commodities/categories")
         if "data" in response:
@@ -334,9 +343,9 @@ async def historical(
     ) -> List[Dict[str, Any]]:
         slug = normalize_futures_slug(contract)
         params = {}
-        if start_date:
+        if start_date is not None:
             params["start_date"] = format_date(start_date)
-        if end_date:
+        if end_date is not None:
             params["end_date"] = format_date(end_date)
         response = await self.client.request(
             method="GET", path=f"/v1/futures/{slug}/historical", params=params
@@ -348,8 +357,8 @@ async def historical(
     async def ohlc(self, contract: str, date: Optional[str] = None) -> Dict[str, Any]:
         slug = normalize_futures_slug(contract)
         params = {}
-        if date:
-            params["date"] = date
+        if date is not None:
+            params["date"] = format_date(date)
         response = await self.client.request(
             method="GET", path=f"/v1/futures/{slug}/ohlc", params=params
         )
@@ -442,9 +451,9 @@ async def history(
         end_date: Optional[Union[str, date, datetime]] = None
     ) -> List[Dict[str, Any]]:
         params = {}
-        if start_date:
+        if start_date is not None:
             params["start_date"] = format_date(start_date)
-        if end_date:
+        if end_date is not None:
             params["end_date"] = format_date(end_date)
         response = await self.client.request(
             method="GET", path=f"/v1/storage/{code}/history", params=params
@@ -476,9 +485,9 @@ async def historical(
         end_date: Optional[Union[str, date, datetime]] = None
     ) -> List[Dict[str, Any]]:
         params = {}
-        if start_date:
+        if start_date is not None:
             params["start_date"] = format_date(start_date)
-        if end_date:
+        if end_date is not None:
             params["end_date"] = format_date(end_date)
         response = await self.client.request(
             method="GET", path="/v1/rig-counts/historical", params=params
@@ -541,9 +550,9 @@ async def historical(
         end_date: Optional[Union[str, date, datetime]] = None
     ) -> List[Dict[str, Any]]:
         params: Dict[str, Any] = {"port": port, "fuel_type": fuel_type}
-        if start_date:
+        if start_date is not None:
             params["start_date"] = format_date(start_date)
-        if end_date:
+        if end_date is not None:
             params["end_date"] = format_date(end_date)
         response = await self.client.request(
             method="GET", path="/v1/bunker-fuels/historical", params=params
@@ -806,9 +815,9 @@ async def state(
         **params,
     ) -> Dict[str, Any]:
         if start_date is not None:
-            params["start_date"] = start_date
+            params["start_date"] = format_date(start_date)
         if end_date is not None:
-            params["end_date"] = end_date
+            params["end_date"] = format_date(end_date)
         response = await self.client.request(
             method="GET", path=f"/v1/well-production/states/{code}", params=params
         )
@@ -857,8 +866,8 @@ async def cycle_time(
     ) -> Dict[str, Any]:
         filters = {
             "state": state,
-            "start_date": start_date,
-            "end_date": end_date,
+            "start_date": format_date(start_date) if start_date is not None else None,
+            "end_date": format_date(end_date) if end_date is not None else None,
             "operator": operator,
             "formation": formation,
             "lat": lat,
@@ -886,8 +895,8 @@ async def cycle_time_cohorts(
     ) -> Dict[str, Any]:
         filters = {
             "state": state,
-            "start_date": start_date,
-            "end_date": end_date,
+            "start_date": format_date(start_date) if start_date is not None else None,
+            "end_date": format_date(end_date) if end_date is not None else None,
             "lat": lat,
             "lng": lng,
             "radius_miles": radius_miles,