feat: make POST /events synchronous with validation feedback

- POST /events now blocks until the event is validated by the pipeline
- Returns 201 Created with eventId and streamId on successful validation
- Returns 202 Accepted with eventId if validation times out (event stored, validation pending)
- Returns 400 Bad Request with validation errors if event fails schema validation
- Uses event-based subscription to aggregator broadcast
- Adds wait_for_event_validation convenience method on AggregatorHandle
- updateDocument (SDK) now uses deep merge for partial content updates (nested objects merged recursively, arrays replaced)

Author: smrz2001

Cargo.lock

@@ -6,6 +6,8 @@ api/openapi.yaml
 docs/BadRequestResponse.md
 docs/ErrorResponse.md
 docs/Event.md
+docs/EventAcceptedResponse.md
+docs/EventCreatedResponse.md
 docs/EventData.md
 docs/EventFeed.md
 docs/EventsGet.md

api-server/.openapi-generator/FILES

@@ -15,7 +15,7 @@ To see how to make this your own, look here:
 [README]((https://openapi-generator.tech))
 
 - API version: 0.58.0
-- Build date: 2025-12-08T21:21:04.734650742Z[Etc/UTC]
+- Build date: 2025-12-14T22:29:40.738562-05:00[America/New_York]
 
 
 
@@ -160,6 +160,8 @@ Method | HTTP request | Description
  - [BadRequestResponse](docs/BadRequestResponse.md)
  - [ErrorResponse](docs/ErrorResponse.md)
  - [Event](docs/Event.md)
+ - [EventAcceptedResponse](docs/EventAcceptedResponse.md)
+ - [EventCreatedResponse](docs/EventCreatedResponse.md)
  - [EventData](docs/EventData.md)
  - [EventFeed](docs/EventFeed.md)
  - [EventsGet](docs/EventsGet.md)

api-server/README.md

@@ -101,8 +101,20 @@ paths:
       requestBody:
         $ref: '#/components/requestBodies/EventData'
       responses:
-        "204":
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventCreatedResponse'
           description: success
+        "202":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventAcceptedResponse'
+          description: Event accepted but validation pending. The event was stored
+            but validation did not complete in time. Use the returned event_id to
+            check status.
         "400":
           content:
             application/json:
@@ -700,6 +712,38 @@ components:
       - data
       title: A Ceramic Event Data Payload
       type: object
+    EventCreatedResponse:
+      description: Returned when an event is successfully created and validated
+      example:
+        eventId: eventId
+        streamId: streamId
+      properties:
+        eventId:
+          description: The CID of the created event
+          type: string
+        streamId:
+          description: The stream ID this event belongs to
+          type: string
+      required:
+      - eventId
+      - streamId
+      title: Response after event creation
+      type: object
+    EventAcceptedResponse:
+      description: Returned when an event is stored but validation did not complete
+        in time. The event may still be validated successfully.
+      properties:
+        eventId:
+          description: The CID of the accepted event
+          type: string
+        message:
+          description: Information about the pending validation status
+          type: string
+      required:
+      - eventId
+      - message
+      title: Response when event is accepted but validation is pending
+      type: object
     EventFeed:
       description: Ceramic event keys as part of a Ceramic Stream
       example:

api-server/api/openapi.yaml

@@ -0,0 +1,11 @@
+# EventAcceptedResponse
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**event_id** | **String** | The CID of the accepted event | 
+**message** | **String** | Information about the pending validation status | 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

api-server/docs/EventAcceptedResponse.md

@@ -0,0 +1,11 @@
+# EventCreatedResponse
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**event_id** | **String** | The CID of the created event | 
+**stream_id** | **String** | The stream ID this event belongs to | 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

api-server/docs/EventCreatedResponse.md

@@ -197,7 +197,7 @@ No authorization required
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # ****
-> (event_data)
+> models::EventCreatedResponse (event_data)
 Creates a new event
 
 ### Required Parameters
@@ -208,7 +208,7 @@ Name | Type | Description  | Notes
 
 ### Return type
 
- (empty response body)
+[**models::EventCreatedResponse**](EventCreatedResponse.md)
 
 ### Authorization
 

api-server/docs/default_api.md

@@ -1060,7 +1060,34 @@ where
             .await?;
 
         match response.status().as_u16() {
-            204 => Ok(EventsPostResponse::Success),
+            201 => {
+                let body = response.into_body();
+                let body = body
+                    .into_raw()
+                    .map_err(|e| ApiError(format!("Failed to read response: {}", e)))
+                    .await?;
+                let body = str::from_utf8(&body)
+                    .map_err(|e| ApiError(format!("Response was not valid UTF8: {}", e)))?;
+                let body =
+                    serde_json::from_str::<models::EventCreatedResponse>(body).map_err(|e| {
+                        ApiError(format!("Response body did not match the schema: {}", e))
+                    })?;
+                Ok(EventsPostResponse::Success(body))
+            }
+            202 => {
+                let body = response.into_body();
+                let body = body
+                    .into_raw()
+                    .map_err(|e| ApiError(format!("Failed to read response: {}", e)))
+                    .await?;
+                let body = str::from_utf8(&body)
+                    .map_err(|e| ApiError(format!("Response was not valid UTF8: {}", e)))?;
+                let body =
+                    serde_json::from_str::<models::EventAcceptedResponse>(body).map_err(|e| {
+                        ApiError(format!("Response body did not match the schema: {}", e))
+                    })?;
+                Ok(EventsPostResponse::EventAcceptedButValidationPending(body))
+            }
             400 => {
                 let body = response.into_body();
                 let body = body

api-server/src/client/mod.rs

@@ -81,7 +81,9 @@ pub enum EventsOptionsResponse {
 #[must_use]
 pub enum EventsPostResponse {
     /// success
-    Success,
+    Success(models::EventCreatedResponse),
+    /// Event accepted but validation pending. The event was stored but validation did not complete in time. Use the returned event_id to check status.
+    EventAcceptedButValidationPending(models::EventAcceptedResponse),
     /// bad request
     BadRequest(models::BadRequestResponse),
     /// Internal server error