fix(client): repair list_orders pagination and add missing page param (#27)

The auto-paginator was emitting combined responses as `{"data": [...], "pagination": {...}}` (generic shape), but `OrderListResponse.from_dict` requires a `meta` block — every list_orders call hit `KeyError: 'meta'` after pagination collected its pages. Auto-paginator now synthesizes a StatusPro-shaped `meta` block describing the combined result as a single page, while keeping the existing `pagination` telemetry as additional properties.

Separately, the OpenAPI spec for `GET /orders` was missing the `page` query parameter the StatusPro server already accepts. The Orders.list helper was forwarding `page=` to a generated function that did not declare it. Spec now declares `page`; client regenerated.

Adds a regression test asserting the combined paginated response round-trips through OrderListResponse.from_dict.

Author: dougborg

docs/statuspro-openapi.yaml

@@ -310,6 +310,13 @@ paths:
         schema:
           type: string
           format: date
+      - name: page
+        in: query
+        required: false
+        description: Page number to return (1-based).
+        schema:
+          type: integer
+          minimum: 1
       - name: per_page
         in: query
         required: false

statuspro_public_api_client/api/orders/list_orders.py

@@ -27,6 +27,7 @@ def _get_kwargs(
     exclude_cancelled: bool | Unset = UNSET,
     due_date_from: datetime.date | Unset = UNSET,
     due_date_to: datetime.date | Unset = UNSET,
+    page: int | Unset = UNSET,
     per_page: int | Unset = 15,
 ) -> dict[str, Any]:
 
@@ -78,6 +79,8 @@ def _get_kwargs(
         json_due_date_to = due_date_to.isoformat()
     params["due_date_to"] = json_due_date_to
 
+    params["page"] = page
+
     params["per_page"] = per_page
 
     params = {k: v for k, v in params.items() if v is not UNSET and v is not None}
@@ -148,6 +151,7 @@ def sync_detailed(
     exclude_cancelled: bool | Unset = UNSET,
     due_date_from: datetime.date | Unset = UNSET,
     due_date_to: datetime.date | Unset = UNSET,
+    page: int | Unset = UNSET,
     per_page: int | Unset = 15,
 ) -> Response[ErrorResponse | OrderListResponse | ValidationErrorResponse]:
     """Retrieve a paginated list of orders
@@ -164,6 +168,7 @@ def sync_detailed(
         exclude_cancelled (bool | Unset):
         due_date_from (datetime.date | Unset):
         due_date_to (datetime.date | Unset):
+        page (int | Unset):
         per_page (int | Unset):  Default: 15.
 
 
@@ -186,6 +191,7 @@ def sync_detailed(
         exclude_cancelled=exclude_cancelled,
         due_date_from=due_date_from,
         due_date_to=due_date_to,
+        page=page,
         per_page=per_page,
     )
 
@@ -208,6 +214,7 @@ def sync(
     exclude_cancelled: bool | Unset = UNSET,
     due_date_from: datetime.date | Unset = UNSET,
     due_date_to: datetime.date | Unset = UNSET,
+    page: int | Unset = UNSET,
     per_page: int | Unset = 15,
 ) -> ErrorResponse | OrderListResponse | ValidationErrorResponse | None:
     """Retrieve a paginated list of orders
@@ -224,6 +231,7 @@ def sync(
         exclude_cancelled (bool | Unset):
         due_date_from (datetime.date | Unset):
         due_date_to (datetime.date | Unset):
+        page (int | Unset):
         per_page (int | Unset):  Default: 15.
 
 
@@ -247,6 +255,7 @@ def sync(
         exclude_cancelled=exclude_cancelled,
         due_date_from=due_date_from,
         due_date_to=due_date_to,
+        page=page,
         per_page=per_page,
     ).parsed
 
@@ -263,6 +272,7 @@ async def asyncio_detailed(
     exclude_cancelled: bool | Unset = UNSET,
     due_date_from: datetime.date | Unset = UNSET,
     due_date_to: datetime.date | Unset = UNSET,
+    page: int | Unset = UNSET,
     per_page: int | Unset = 15,
 ) -> Response[ErrorResponse | OrderListResponse | ValidationErrorResponse]:
     """Retrieve a paginated list of orders
@@ -279,6 +289,7 @@ async def asyncio_detailed(
         exclude_cancelled (bool | Unset):
         due_date_from (datetime.date | Unset):
         due_date_to (datetime.date | Unset):
+        page (int | Unset):
         per_page (int | Unset):  Default: 15.
 
 
@@ -301,6 +312,7 @@ async def asyncio_detailed(
         exclude_cancelled=exclude_cancelled,
         due_date_from=due_date_from,
         due_date_to=due_date_to,
+        page=page,
         per_page=per_page,
     )
 
@@ -321,6 +333,7 @@ async def asyncio(
     exclude_cancelled: bool | Unset = UNSET,
     due_date_from: datetime.date | Unset = UNSET,
     due_date_to: datetime.date | Unset = UNSET,
+    page: int | Unset = UNSET,
     per_page: int | Unset = 15,
 ) -> ErrorResponse | OrderListResponse | ValidationErrorResponse | None:
     """Retrieve a paginated list of orders
@@ -337,6 +350,7 @@ async def asyncio(
         exclude_cancelled (bool | Unset):
         due_date_from (datetime.date | Unset):
         due_date_to (datetime.date | Unset):
+        page (int | Unset):
         per_page (int | Unset):  Default: 15.
 
 
@@ -361,6 +375,7 @@ async def asyncio(
             exclude_cancelled=exclude_cancelled,
             due_date_from=due_date_from,
             due_date_to=due_date_to,
+            page=page,
             per_page=per_page,
         )
     ).parsed

statuspro_public_api_client/statuspro_client.py

@@ -538,13 +538,29 @@ async def _handle_paginated_request(self, request: httpx.Request) -> httpx.Respo
             # Original endpoint returned a raw JSON list - preserve that format
             combined_content = json.dumps(all_data).encode()
         else:
-            combined_data: dict[str, Any] = {"data": all_data}
-            # Add pagination metadata
+            # StatusPro wrapped list shape: {"data": [...], "meta": {...}}.
+            # Generated response models (e.g. OrderListResponse.from_dict)
+            # require `meta`, so synthesize one describing the combined result
+            # as a single page containing every collected item.
+            total_items = len(all_data)
+            combined_data: dict[str, Any] = {
+                "data": all_data,
+                "meta": {
+                    "current_page": 1,
+                    "last_page": 1,
+                    "per_page": total_items,
+                    "total": total_items,
+                    "from": 1 if total_items else None,
+                    "to": total_items if total_items else None,
+                },
+            }
+            # Telemetry about the underlying pagination walk; lands in
+            # additional_properties on the parsed model.
             if total_pages:
                 combined_data["pagination"] = {
                     "total_pages": total_pages,
                     "collected_pages": page_num,
-                    "total_items": len(all_data),
+                    "total_items": total_items,
                     "auto_paginated": True,
                 }
             combined_content = json.dumps(combined_data).encode()

tests/test_statuspro_client.py

@@ -461,6 +461,80 @@ async def mock_aread():
         assert combined_data["pagination"]["collected_pages"] == 3
         assert combined_data["pagination"]["auto_paginated"] is True
 
+    @pytest.mark.asyncio
+    async def test_auto_pagination_emits_statuspro_meta_shape(
+        self, transport, mock_wrapped_transport
+    ):
+        """Combined paginated response must include a `meta` block parseable by
+        OrderListResponse.from_dict (StatusPro's wrapped list schema requires it).
+        """
+        from statuspro_public_api_client.models.order_list_response import (
+            OrderListResponse,
+        )
+
+        page1 = {
+            "data": [
+                {"id": 1, "name": "#1", "order_number": "1"},
+                {"id": 2, "name": "#2", "order_number": "2"},
+            ],
+            "meta": {
+                "current_page": 1,
+                "last_page": 2,
+                "per_page": 2,
+                "total": 3,
+                "from": 1,
+                "to": 2,
+            },
+        }
+        page2 = {
+            "data": [{"id": 3, "name": "#3", "order_number": "3"}],
+            "meta": {
+                "current_page": 2,
+                "last_page": 2,
+                "per_page": 2,
+                "total": 3,
+                "from": 3,
+                "to": 3,
+            },
+        }
+
+        def create_response(data):
+            mock_resp = MagicMock(spec=httpx.Response)
+            mock_resp.status_code = 200
+            mock_resp.json.return_value = data
+            mock_resp.headers = {}
+
+            async def mock_aread():
+                pass
+
+            mock_resp.aread = mock_aread
+            return mock_resp
+
+        mock_wrapped_transport.handle_async_request.side_effect = [
+            create_response(page1),
+            create_response(page2),
+        ]
+
+        request = httpx.Request(method="GET", url="https://api.example.com/orders")
+        response = await transport.handle_async_request(request)
+
+        combined = json.loads(response.content)
+        # All items concatenated
+        assert [item["id"] for item in combined["data"]] == [1, 2, 3]
+        # StatusPro `meta` block must be present and well-formed
+        assert "meta" in combined, (
+            "Combined paginated response must emit a `meta` block — "
+            "OrderListResponse.from_dict() requires it."
+        )
+        assert combined["meta"]["current_page"] == 1
+        assert combined["meta"]["last_page"] == 1
+        assert combined["meta"]["per_page"] == 3
+        assert combined["meta"]["total"] == 3
+        # And the response must round-trip through the generated parser
+        parsed = OrderListResponse.from_dict(combined)
+        assert len(parsed.data) == 3
+        assert parsed.meta.total == 3
+
 
 @pytest.mark.unit
 class TestStatusProClient: