@epilot/erp-integration-client 0.15.0 → 0.15.2

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.17.2",
+    "version": "0.22.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -17,12 +17,13 @@
     {
       "name": "integrations",
       "description": "Integration and Use Case management endpoints"
+    },
+    {
+      "name": "monitoring",
+      "description": "Monitoring and analytics endpoints"
     }
   ],
   "servers": [
-    {
-      "url": "https://erp-integration-api.sls.epilot.io"
-    },
     {
       "url": "https://erp-integration-api.sls.epilot.io"
     }
@@ -1560,6 +1561,227 @@
         }
       }
     },
+    "/v2/integrations": {
+      "get": {
+        "operationId": "listIntegrationsV2",
+        "summary": "listIntegrationsV2",
+        "description": "Retrieve all integrations with embedded use cases for the authenticated organization",
+        "tags": [
+          "integrations"
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved integrations with use cases",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "integrations"
+                  ],
+                  "properties": {
+                    "integrations": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/IntegrationWithUseCases"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "post": {
+        "operationId": "createIntegrationV2",
+        "summary": "createIntegrationV2",
+        "description": "Create a new integration with embedded use cases.\n",
+        "tags": [
+          "integrations"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertIntegrationWithUseCasesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Integration created successfully with use cases",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/IntegrationWithUseCases"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/integrations/{integrationId}": {
+      "get": {
+        "operationId": "getIntegrationV2",
+        "summary": "getIntegrationV2",
+        "description": "Retrieve a specific integration with all its embedded use cases",
+        "tags": [
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved integration with use cases",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/IntegrationWithUseCases"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "description": "Integration not found"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateIntegrationV2",
+        "summary": "updateIntegrationV2",
+        "description": "Update an existing integration with embedded use cases.\nThe integration must already exist.\nUse cases are updated declaratively:\n- Use cases in the request with matching IDs are updated\n- Use cases in the request without matching IDs are created\n- Existing use cases not in the request are deleted\n",
+        "tags": [
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID (client-provided)",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertIntegrationWithUseCasesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Integration updated successfully with use cases",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/IntegrationWithUseCases"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "description": "Integration not found"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteIntegrationV2",
+        "summary": "deleteIntegrationV2",
+        "description": "Delete an integration and all its use cases",
+        "tags": [
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Integration deleted successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "description": "Integration not found"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/integrations/{integrationId}/app-mapping": {
       "put": {
         "operationId": "setIntegrationAppMapping",
@@ -1684,53 +1906,153 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "EpilotAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "Authorization header with epilot OAuth2 bearer token",
-        "bearerFormat": "JWT"
-      }
     },
-    "schemas": {
-      "ErrorResponseBase": {
-        "type": "object",
-        "properties": {
-          "code": {
-            "type": "string",
-            "description": "Computer-readable error code"
-          },
-          "message": {
-            "type": "string",
-            "description": "Error message"
+    "/v1/integrations/{integrationId}/monitoring/events": {
+      "post": {
+        "operationId": "queryMonitoringEvents",
+        "summary": "queryMonitoringEvents",
+        "description": "Query ERP sync monitoring events for a specific integration.\nReturns detailed information about inbound/outbound sync events,\nincluding success rates, error breakdowns, and processing metrics.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
           }
-        }
-      },
-      "ErpEvent": {
-        "type": "object",
-        "required": [
-          "event_type",
-          "object_type",
-          "timestamp",
-          "format",
-          "payload"
         ],
-        "properties": {
-          "event_type": {
-            "type": "string",
-            "enum": [
-              "CREATE",
-              "UPDATE",
-              "DELETE"
-            ],
-            "description": "Type of event (create, update, delete)"
-          },
-          "object_type": {
-            "type": "string",
-            "description": "Type of the object being updated (business_partner, contract_account, etc.)"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/QueryMonitoringEventsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/QueryMonitoringEventsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/monitoring/stats": {
+      "post": {
+        "operationId": "getMonitoringStats",
+        "summary": "getMonitoringStats",
+        "description": "Get aggregated statistics for ERP sync monitoring events for a specific integration.\nReturns summary metrics like total events, success/error counts,\nand breakdowns by use case, direction, and sync type.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetMonitoringStatsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetMonitoringStatsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "ErrorResponseBase": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Computer-readable error code"
+          },
+          "message": {
+            "type": "string",
+            "description": "Error message"
+          }
+        }
+      },
+      "ErpEvent": {
+        "type": "object",
+        "required": [
+          "event_type",
+          "object_type",
+          "timestamp",
+          "format",
+          "payload"
+        ],
+        "properties": {
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
+              "UPDATE",
+              "DELETE"
+            ],
+            "description": "Type of event (create, update, delete)"
+          },
+          "object_type": {
+            "type": "string",
+            "description": "Type of the object being updated (business_partner, contract_account, etc.). Corresponds to \"Event Name\" from the integration UI."
           },
           "timestamp": {
             "type": "string",
@@ -2016,7 +2338,7 @@
           }
         }
       },
-      "UseCase": {
+      "UseCaseBase": {
         "type": "object",
         "required": [
           "id",
@@ -2051,8 +2373,7 @@
             "description": "Use case type"
           },
           "enabled": {
-            "type": "boolean",
-            "description": "Whether the use case is enabled"
+            "type": "boolean"
           },
           "change_description": {
             "type": "string",
@@ -2069,8 +2390,60 @@
             "format": "date-time",
             "description": "ISO-8601 timestamp when the use case was last updated"
           }
-        },
-        "anyOf": [
+        }
+      },
+      "InboundUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "inbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "OutboundUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "outbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "UseCase": {
+        "oneOf": [
           {
             "$ref": "#/components/schemas/InboundUseCase"
           },
@@ -2086,42 +2459,6 @@
           }
         }
       },
-      "InboundUseCase": {
-        "type": "object",
-        "required": [
-          "type"
-        ],
-        "properties": {
-          "type": {
-            "type": "string",
-            "enum": [
-              "inbound"
-            ],
-            "description": "Use case type"
-          },
-          "configuration": {
-            "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
-          }
-        }
-      },
-      "OutboundUseCase": {
-        "type": "object",
-        "required": [
-          "type"
-        ],
-        "properties": {
-          "type": {
-            "type": "string",
-            "enum": [
-              "outbound"
-            ],
-            "description": "Use case type"
-          },
-          "configuration": {
-            "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
-          }
-        }
-      },
       "CreateUseCaseRequest": {
         "oneOf": [
           {
@@ -2777,14 +3114,13 @@
       "IntegrationMeterReading": {
         "type": "object",
         "required": [
-          "jsonataExpression",
           "meter",
           "fields"
         ],
         "properties": {
           "jsonataExpression": {
             "type": "string",
-            "description": "JSONata expression to extract meter reading items from the event data"
+            "description": "Optional JSONata expression to extract meter reading items from the event data.\nIf not provided, the entire payload is used as the reading data.\nUseful when you need to extract an array of readings from a nested structure (e.g., \"$.readings\").\n"
           },
           "reading_matching": {
             "type": "string",
@@ -3050,34 +3386,206 @@
         ],
         "description": "Type hint for repeatable fields that require special search handling.\nThese fields are stored as arrays of objects (e.g., email: [{ email: \"value\" }]).\n"
       },
-      "ReplayEventsRequest": {
+      "IntegrationWithUseCases": {
         "type": "object",
+        "description": "Integration with embedded use cases for atomic CRUD operations",
         "required": [
-          "event_ids"
+          "id",
+          "orgId",
+          "name",
+          "use_cases",
+          "created_at",
+          "updated_at"
         ],
         "properties": {
-          "event_ids": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier for the integration"
+          },
+          "orgId": {
+            "type": "string",
+            "description": "Organization ID"
+          },
+          "name": {
+            "type": "string",
+            "description": "Integration name"
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional description of the integration"
+          },
+          "use_cases": {
             "type": "array",
+            "description": "All use cases belonging to this integration",
             "items": {
-              "type": "string"
-            },
-            "minItems": 1,
-            "maxItems": 100,
-            "description": "List of event IDs to replay. Maximum 100 events per request."
+              "$ref": "#/components/schemas/UseCase"
+            }
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp when the integration was created"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp when the integration was last updated"
           }
         }
       },
-      "QueryEventsRequest": {
+      "UpsertIntegrationWithUseCasesRequest": {
         "type": "object",
+        "description": "Request to create or update an integration with embedded use cases (upsert).\nThis is a declarative operation - the request represents the desired state.\n",
+        "required": [
+          "name"
+        ],
         "properties": {
-          "event_id": {
+          "name": {
             "type": "string",
-            "description": "Filter by event ID"
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Integration name"
           },
-          "event_type": {
+          "description": {
             "type": "string",
-            "enum": [
-              "CREATE",
+            "maxLength": 1000,
+            "description": "Optional description of the integration"
+          },
+          "use_cases": {
+            "type": "array",
+            "description": "Full list of use cases (declarative). This replaces ALL existing use cases.\n- Use cases with an `id` field matching an existing use case will be updated\n- Use cases without an `id` or with a non-matching `id` will be created\n- Existing use cases not in this list will be deleted\n",
+            "items": {
+              "$ref": "#/components/schemas/EmbeddedUseCaseRequest"
+            }
+          }
+        }
+      },
+      "EmbeddedUseCaseRequest": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedInboundUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "inbound": "#/components/schemas/EmbeddedInboundUseCaseRequest",
+            "outbound": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
+          }
+        }
+      },
+      "EmbeddedUseCaseRequestBase": {
+        "type": "object",
+        "required": [
+          "name",
+          "type",
+          "enabled"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional use case ID for update matching.\n- If provided and matches an existing use case, that use case is updated\n- If provided but no match, a new use case with this ID is created\n- If omitted, a new use case with auto-generated ID is created\n"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Use case name"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether the use case is enabled"
+          },
+          "change_description": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Optional description of this change (like a commit message)"
+          }
+        }
+      },
+      "EmbeddedInboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "inbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "EmbeddedOutboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "outbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "ReplayEventsRequest": {
+        "type": "object",
+        "required": [
+          "event_ids"
+        ],
+        "properties": {
+          "event_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "maxItems": 100,
+            "description": "List of event IDs to replay. Maximum 100 events per request."
+          }
+        }
+      },
+      "QueryEventsRequest": {
+        "type": "object",
+        "properties": {
+          "event_id": {
+            "type": "string",
+            "description": "Filter by event ID"
+          },
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
               "UPDATE",
               "DELETE"
             ],
@@ -3117,6 +3625,334 @@
             }
           }
         }
+      },
+      "QueryMonitoringEventsRequest": {
+        "type": "object",
+        "properties": {
+          "use_case_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Filter by use case ID"
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound"
+            ],
+            "description": "Filter by sync direction"
+          },
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
+              "UPDATE",
+              "DELETE",
+              "TRIGGER"
+            ],
+            "description": "Filter by event type"
+          },
+          "sync_type": {
+            "type": "string",
+            "enum": [
+              "entity",
+              "meter_reading",
+              "webhook"
+            ],
+            "description": "Filter by sync type"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "success",
+              "error",
+              "skipped"
+            ],
+            "description": "Filter by processing status"
+          },
+          "error_category": {
+            "type": "string",
+            "enum": [
+              "validation",
+              "configuration",
+              "downstream_api",
+              "timeout",
+              "system",
+              "webhook_delivery"
+            ],
+            "description": "Filter by error category (only applicable when status=error)"
+          },
+          "correlation_id": {
+            "type": "string",
+            "description": "Filter by correlation ID"
+          },
+          "object_type": {
+            "type": "string",
+            "description": "Filter by object type (e.g., 'contract', 'meter')"
+          },
+          "event_id": {
+            "type": "string",
+            "description": "Filter by event ID to find a specific event"
+          },
+          "from_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events from this date (inclusive)",
+            "example": "2025-01-01T00:00:00Z"
+          },
+          "to_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events until this date (inclusive)",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of results to return",
+            "example": 50,
+            "default": 50,
+            "minimum": 1,
+            "maximum": 100
+          },
+          "cursor": {
+            "type": "object",
+            "description": "Cursor for pagination",
+            "properties": {
+              "completed_at": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Timestamp from the last event in the previous page"
+              },
+              "event_id": {
+                "type": "string",
+                "description": "Event ID from the last event in the previous page"
+              }
+            }
+          }
+        }
+      },
+      "GetMonitoringStatsRequest": {
+        "type": "object",
+        "properties": {
+          "use_case_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Filter by use case ID"
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound"
+            ],
+            "description": "Filter by sync direction"
+          },
+          "from_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Start date for statistics period (inclusive)",
+            "example": "2025-01-01T00:00:00Z"
+          },
+          "to_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "End date for statistics period (inclusive)",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "group_by": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "direction",
+                "use_case_id",
+                "sync_type",
+                "status",
+                "error_category",
+                "object_type",
+                "date"
+              ]
+            },
+            "description": "Fields to group statistics by",
+            "example": [
+              "direction",
+              "status"
+            ]
+          }
+        }
+      },
+      "MonitoringEvent": {
+        "type": "object",
+        "required": [
+          "org_id",
+          "event_id",
+          "direction",
+          "event_type",
+          "object_type",
+          "sync_type",
+          "status",
+          "received_at",
+          "completed_at"
+        ],
+        "properties": {
+          "org_id": {
+            "type": "string",
+            "description": "Organization ID"
+          },
+          "event_id": {
+            "type": "string",
+            "description": "Unique event identifier"
+          },
+          "correlation_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Correlation ID for tracing related events"
+          },
+          "integration_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Integration ID"
+          },
+          "use_case_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Use case ID"
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound"
+            ],
+            "description": "Sync direction"
+          },
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
+              "UPDATE",
+              "DELETE",
+              "TRIGGER"
+            ],
+            "description": "Type of event"
+          },
+          "object_type": {
+            "type": "string",
+            "description": "Type of object being synced (e.g., 'contract', 'meter')"
+          },
+          "sync_type": {
+            "type": "string",
+            "enum": [
+              "entity",
+              "meter_reading",
+              "webhook"
+            ],
+            "description": "Type of sync operation"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "success",
+              "error",
+              "skipped"
+            ],
+            "description": "Processing status"
+          },
+          "error_code": {
+            "type": "string",
+            "nullable": true,
+            "description": "Error code (when status=error)"
+          },
+          "error_message": {
+            "type": "string",
+            "nullable": true,
+            "description": "Error message (when status=error)"
+          },
+          "error_category": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "validation",
+              "configuration",
+              "downstream_api",
+              "timeout",
+              "system",
+              "webhook_delivery"
+            ],
+            "description": "Error category (when status=error)"
+          },
+          "processing_duration_ms": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Processing duration in milliseconds"
+          },
+          "target_url": {
+            "type": "string",
+            "nullable": true,
+            "description": "Target URL for outbound requests"
+          },
+          "http_status_code": {
+            "type": "integer",
+            "nullable": true,
+            "description": "HTTP status code from target (outbound only)"
+          },
+          "received_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the event was received"
+          },
+          "completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When processing completed"
+          }
+        }
+      },
+      "MonitoringStats": {
+        "type": "object",
+        "required": [
+          "total_events",
+          "success_count",
+          "error_count",
+          "skipped_count"
+        ],
+        "properties": {
+          "total_events": {
+            "type": "integer",
+            "description": "Total number of events in the period"
+          },
+          "success_count": {
+            "type": "integer",
+            "description": "Number of successful events"
+          },
+          "error_count": {
+            "type": "integer",
+            "description": "Number of failed events"
+          },
+          "skipped_count": {
+            "type": "integer",
+            "description": "Number of skipped events"
+          },
+          "success_rate": {
+            "type": "number",
+            "format": "float",
+            "description": "Success rate as percentage (0-100)"
+          },
+          "last_error_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "Timestamp of the most recent error"
+          },
+          "breakdown": {
+            "type": "array",
+            "description": "Statistics breakdown by requested group_by fields",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
       }
     },
     "responses": {
@@ -3160,6 +3996,53 @@
           }
         }
       },
+      "QueryMonitoringEventsResponse": {
+        "description": "Monitoring events queried successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "data": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/MonitoringEvent"
+                  },
+                  "description": "List of monitoring events"
+                },
+                "next_cursor": {
+                  "type": "object",
+                  "nullable": true,
+                  "description": "Cursor to fetch the next page. Null if no more results.",
+                  "properties": {
+                    "completed_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "event_id": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "has_more": {
+                  "type": "boolean",
+                  "description": "Indicates if more results are available"
+                }
+              }
+            }
+          }
+        }
+      },
+      "GetMonitoringStatsResponse": {
+        "description": "Monitoring statistics retrieved successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/MonitoringStats"
+            }
+          }
+        }
+      },
       "ReplayEventsResponse": {
         "description": "Events replay initiated",
         "content": {