Add parameter support for all API endpoints

octopus_energy/rest_client.py

@@ -200,33 +200,80 @@ async def get_gas_consumption_v1(
             },
         )
 
-    async def get_products_v1(self) -> dict:
+    async def get_products_v1(
+        self,
+        page_num: int = None,
+        page_size: int = None,
+        is_variable: bool = None,
+        is_green: bool = None,
+        is_tracker: bool = None,
+        is_prepay: bool = None,
+        is_business: bool = None,
+        available_at: datetime = None,
+    ) -> dict:
         """Gets octopus energy products.
 
+        Args:
+            page_num: (Optional) The page number to load.
+            page_size: (Optional) How many results per page.
+            is_variable (Optional): Activate filter and include variable products in the results.
+            is_green (Optional): Activate filter and include green products in the results.
+            is_tracker (Optional): Activate filter and include tracker products in the results.
+            is_prepay (Optional): Activate filter and include prepay products in the results.
+            is_business (Optional): Activate filter and include business products in the results.
+            available_at (Optional): Include products available for new agreements on the given
+                                     timestamp. Defaults to current datetime, effectively showing
+                                     products that are currently available.
+
         Returns:
             A dictionary containing the products response.
 
         """
-        return await self._get(["v1", "products"])
+        return await self._get(
+            ["v1", "products"],
+            {
+                "page": page_num,
+                "page_size": page_size,
+                "is_variable": is_variable,
+                "is_green": is_green,
+                "is_tracker": is_tracker,
+                "is_prepay": is_prepay,
+                "is_business": is_business,
+                "available_at": to_timestamp_str(available_at) if available_at else None,
+            },
+        )
 
-    async def get_product_v1(self, product_code: str) -> dict:
+    async def get_product_v1(self, product_code: str, tariffs_active_at: datetime = None) -> dict:
         """Gets detailed information about a specific octopus energy product.
 
         Args:
             product_code: The product code to retrieve.
+            tariffs_active_at (Optional): If specified, returns the tariff rates at the timestamp
+                                          requested.
 
         Returns:
             A dictionary containing the product details response.
 
         """
-        return await self._get(["v1", "products", product_code])
+        return await self._get(
+            ["v1", "products", product_code],
+            {
+                "tariffs_active_at": to_timestamp_str(tariffs_active_at)
+                if tariffs_active_at is not None
+                else None
+            },
+        )
 
     async def get_tariff_v1(
         self,
         product_code: str,
         tariff_type: EnergyTariffType,
         tariff_code: str,
         rate_type: RateType,
+        page_num: int = None,
+        page_size: int = None,
+        period_from: datetime = None,
+        period_to: datetime = None,
     ) -> dict:
         """Gets tariff information about a specific octopus energy tariff.
 
@@ -235,13 +282,23 @@ async def get_tariff_v1(
             tariff_type: The type of tariff to get the details of.
             tariff_code: The tariff code to get the details of.
             rate_type: The rate within the tariff to retrieve.
+            page_num: (Optional) The page number to load.
+            page_size: (Optional) How many results per page.
+            period_from: (Optional) The timestamp (inclusive) from where to begin returning results.
+            period_to: (Optional) The timestamp (exclusive) at which to end returning results.
 
         Returns:
             A dictionary containing the tariff details response.
 
         """
         return await self._get(
-            ["v1", "products", product_code, tariff_type.value, tariff_code, rate_type.value]
+            ["v1", "products", product_code, tariff_type.value, tariff_code, rate_type.value],
+            {
+                "page": page_num,
+                "page_size": page_size,
+                "period_from": to_timestamp_str(period_from),
+                "period_to": to_timestamp_str(period_to),
+            },
         )
 
     async def renew_business_tariff(self, account_number: str, renewal_data: dict) -> dict:

readme.md

@@ -29,8 +29,10 @@ You can obtain your API token and meter information from the [Octopus Energy Dev
 Dashboard][octo dashboard].
 
 ### REST Client Wrapper
-The REST client wrapper is a slim shim over the REST API that returns dictionaries as responses. This is perfect if you
-want something quick and dirty.
+The REST client wrapper is a slim shim over the REST API that returns dictionaries as responses. 
+
+Note that you should reference the [Octopus Energy API documentation][octo api] for detailed notes on the API responses  
+and specifics around the request parameters.
 
 ```python
 from octopus_energy import OctopusEnergyRestClient
@@ -39,9 +41,10 @@ api_token="sk_live_your-token"
 mprn = "your-mprn"
 serial_number = "your-meter-serial-number"
 
-async with OctopusEnergyClient(api_token) as client:
+async with OctopusEnergyRestClient(api_token) as client:
   consumption = await client.get_gas_consumption_v1(mprn, serial_number)
 ```
 
 [github]: https://github.com/markallanson/octopus-energy
 [octo dashboard]: https://octopus.energy/dashboard/developer/
+[octo api]: https://developer.octopus.energy/docs/api/

tests/test_e2e.py

@@ -121,33 +121,65 @@ async def get(client):
     )
 
 
+@freeze_time("2021-01-01 01:11:11")
 @pytest.mark.asyncio
 async def test_get_products_v1(mock_aioresponses: aioresponses):
     async def get(client):
-        return await client.get_products_v1()
+        return await client.get_products_v1(
+            page_num=1,
+            page_size=10,
+            is_business=True,
+            is_green=True,
+            is_tracker=True,
+            is_variable=True,
+            is_prepay=True,
+            available_at=datetime.now(tz=tzoffset("CEST", 2)),
+        )
 
-    await _run_get_test("v1/products", "get_products_response.json", get, mock_aioresponses)
+    await _run_get_test(
+        "v1/products?page=1&page_size=10&is_variable=True&is_green=True&is_tracker=True"
+        "&is_prepay=True&is_business=True&available_at=2021-01-01T01%3A11%3A13%2B00%3A00%3A02",
+        "get_products_response.json",
+        get,
+        mock_aioresponses,
+    )
 
 
+@freeze_time("2021-01-01 01:11:11")
 @pytest.mark.asyncio
 async def test_get_product_v1(mock_aioresponses: aioresponses):
     async def get(client):
-        return await client.get_product_v1("product_id")
+        return await client.get_product_v1(
+            "product_id", tariffs_active_at=datetime.now(tz=tzoffset("CEST", 2))
+        )
 
     await _run_get_test(
-        "v1/products/product_id", "get_product_response.json", get, mock_aioresponses
+        "v1/products/product_id?tariffs_active_at=2021-01-01T01%3A11%3A13%2B00%3A00%3A02",
+        "get_product_response.json",
+        get,
+        mock_aioresponses,
     )
 
 
+@freeze_time("2021-01-01 01:11:11")
 @pytest.mark.asyncio
 async def test_get_tariff_v1(mock_aioresponses: aioresponses):
     async def get(client):
         return await client.get_tariff_v1(
-            "product_id", EnergyTariffType.GAS, "tariff_code", RateType.STANDING_CHARGES
+            "product_id",
+            EnergyTariffType.GAS,
+            "tariff_code",
+            RateType.STANDING_CHARGES,
+            page_num=1,
+            page_size=10,
+            period_from=datetime.now(tz=tzoffset("CEST", 2)),
+            period_to=datetime.now(tz=tzoffset("CEST", 2)),
         )
 
     await _run_get_test(
-        "v1/products/product_id/gas-tariffs/tariff_code/standing-charges",
+        "v1/products/product_id/gas-tariffs/tariff_code/standing-charges?page=1&page_size=10"
+        "&period_from=2021-01-01T01%3A11%3A13%2B00%3A00%3A02"
+        "&period_to=2021-01-01T01%3A11%3A13%2B00%3A00%3A02",
         "get_tariff_response.json",
         get,
         mock_aioresponses,