add bulk_create_parsed() for typed results from bulk create operations

Author: purificant

src/bubble_data_api_client/__init__.py

@@ -24,6 +24,7 @@
 from bubble_data_api_client.types import (
     BubbleField,
     BubbleUID,
+    BulkCreateItemResult,
     OnMultiple,
     OptionalBubbleUID,
     OptionalBubbleUIDs,
@@ -51,6 +52,7 @@
     # types
     "BubbleField",
     "BubbleUID",
+    "BulkCreateItemResult",
     "OnMultiple",
     "OptionalBubbleUID",
     "OptionalBubbleUIDs",

src/bubble_data_api_client/client/raw_client.py

@@ -20,7 +20,12 @@
     PartialFailureError,
 )
 from bubble_data_api_client.transport import Transport
-from bubble_data_api_client.types import BubbleField, CreateOrUpdateResult, OnMultiple
+from bubble_data_api_client.types import (
+    BubbleField,
+    BulkCreateItemResult,
+    CreateOrUpdateResult,
+    OnMultiple,
+)
 
 
 # https://manual.bubble.io/core-resources/api/the-bubble-api/the-data-api/data-api-requests#sorting
@@ -48,7 +53,7 @@ class RawClient:
     These handle response parsing and return typed values. Use these when you
     don't need raw HTTP access.
 
-        count, exists, create_or_update
+        count, exists, create_or_update, bulk_create_parsed
 
     For ORM-style access with model classes, use BubbleModel instead.
 
@@ -89,13 +94,36 @@ async def create(self, typename: str, data: typing.Any) -> httpx.Response:
     async def bulk_create(self, typename: str, data: list[typing.Any]) -> httpx.Response:
         """Create multiple things in a single request using newline-delimited JSON.
 
-        Response is text/plain with one JSON object per line: {"status":"success","id":"..."}
+        Response is text/plain with one JSON object per line, in the same order as input:
+            Success: {"status":"success","id":"1234x5678"}
+            Error: {"status":"error","message":"Could not parse as JSON: ..."}
+
+        Partial failures are possible where some items succeed and others fail.
         """
         return await self._transport.post_text(
             url=f"/{typename}/bulk",
             content="\n".join(json.dumps(item) for item in data),
         )
 
+    async def bulk_create_parsed(self, typename: str, data: list[typing.Any]) -> list[BulkCreateItemResult]:
+        """Create multiple things and return parsed results for each item.
+
+        Returns a list of results in the same order as input data. Each result
+        contains status, id (on success), and message (on error).
+        """
+        response = await self.bulk_create(typename=typename, data=data)
+        results: list[BulkCreateItemResult] = []
+        for line in response.text.strip().split("\n"):
+            parsed = json.loads(line)
+            results.append(
+                BulkCreateItemResult(
+                    status=parsed["status"],
+                    id=parsed.get("id"),
+                    message=parsed.get("message"),
+                )
+            )
+        return results
+
     async def delete(self, typename: str, uid: str) -> httpx.Response:
         """Delete a thing by its unique ID."""
         return await self._transport.delete(f"/{typename}/{uid}")

src/bubble_data_api_client/types.py

@@ -1,7 +1,7 @@
 """Bubble platform types for use with Pydantic models."""
 
 from enum import StrEnum
-from typing import Annotated, Any, TypedDict
+from typing import Annotated, Any, Literal, TypedDict
 
 from pydantic import AfterValidator, BeforeValidator
 
@@ -37,6 +37,18 @@ class CreateOrUpdateResult(TypedDict):
     created: bool
 
 
+class BulkCreateItemResult(TypedDict):
+    """Result for a single item in a bulk create operation.
+
+    On success: status="success", id=<uid>, message=None
+    On error: status="error", id=None, message=<error description>
+    """
+
+    status: Literal["success", "error"]
+    id: str | None
+    message: str | None
+
+
 def _validate_bubble_uid(value: str) -> str:
     """Validate that a string is a valid Bubble UID."""
     if not is_bubble_uid(value):

src/tests/integration/test_raw_client.py

@@ -79,6 +79,37 @@ async def test_bulk_create_success(typename: str, bubble_raw_client: raw_client.
                 warnings.warn(f"cleanup failed for {uid}: {e}", stacklevel=2)
 
 
+async def test_bulk_create_parsed_success(typename: str, bubble_raw_client: raw_client.RawClient):
+    """Test that bulk_create_parsed returns typed results."""
+    created_ids: list[str] = []
+
+    try:
+        results = await bubble_raw_client.bulk_create_parsed(
+            typename=typename,
+            data=[{"text": "parsed test 1"}, {"text": "parsed test 2"}],
+        )
+
+        assert len(results) == 2
+        for result in results:
+            assert result["status"] == "success"
+            assert result["id"] is not None
+            assert result["message"] is None
+            created_ids.append(result["id"])
+
+        # verify items exist with correct data
+        expected_texts = ["parsed test 1", "parsed test 2"]
+        for uid, expected_text in zip(created_ids, expected_texts, strict=True):
+            retrieve_response = await bubble_raw_client.retrieve(typename=typename, uid=uid)
+            assert retrieve_response.json()["response"]["text"] == expected_text
+
+    finally:
+        for uid in created_ids:
+            try:
+                await bubble_raw_client.delete(typename=typename, uid=uid)
+            except Exception as e:
+                warnings.warn(f"cleanup failed for {uid}: {e}", stacklevel=2)
+
+
 async def test_update_success(typename: str, test_thing_id: str, bubble_raw_client: raw_client.RawClient):
     """Test that we can update a thing."""
     response = await bubble_raw_client.update(typename=typename, uid=test_thing_id, data={"text": "updated text"})

src/tests/unit/client/test_raw_client.py

@@ -60,6 +60,52 @@ async def test_bulk_create(configured_client: None) -> None:
     assert request_content == '{"name": "Alice"}\n{"name": "Bob"}'
 
 
+@respx.mock
+async def test_bulk_create_parsed_success(configured_client: None) -> None:
+    """Test that bulk_create_parsed returns parsed results on success."""
+    mock_response_text = '{"status":"success","id":"1234x5678"}\n{"status":"success","id":"1234x5679"}'
+    respx.post("https://example.com/customer/bulk").mock(
+        return_value=httpx.Response(200, text=mock_response_text, headers={"content-type": "text/plain"})
+    )
+
+    async with raw_client.RawClient() as client:
+        results = await client.bulk_create_parsed(
+            typename="customer",
+            data=[{"name": "Alice"}, {"name": "Bob"}],
+        )
+
+    assert len(results) == 2
+    assert results[0]["status"] == "success"
+    assert results[0]["id"] == "1234x5678"
+    assert results[0]["message"] is None
+    assert results[1]["status"] == "success"
+    assert results[1]["id"] == "1234x5679"
+    assert results[1]["message"] is None
+
+
+@respx.mock
+async def test_bulk_create_parsed_partial_failure(configured_client: None) -> None:
+    """Test that bulk_create_parsed returns parsed results on partial failure."""
+    mock_response_text = '{"status":"success","id":"1234x5678"}\n{"status":"error","message":"Invalid field value"}'
+    respx.post("https://example.com/customer/bulk").mock(
+        return_value=httpx.Response(200, text=mock_response_text, headers={"content-type": "text/plain"})
+    )
+
+    async with raw_client.RawClient() as client:
+        results = await client.bulk_create_parsed(
+            typename="customer",
+            data=[{"name": "Alice"}, {"name": ""}],
+        )
+
+    assert len(results) == 2
+    assert results[0]["status"] == "success"
+    assert results[0]["id"] == "1234x5678"
+    assert results[0]["message"] is None
+    assert results[1]["status"] == "error"
+    assert results[1]["id"] is None
+    assert results[1]["message"] == "Invalid field value"
+
+
 @respx.mock
 async def test_find_with_parameters(configured_client: None) -> None:
     """Test that find passes optional parameters correctly."""