@epilot/sdk 2.2.6 → 2.2.7

package/definitions/erp-integration.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.50.1",
+    "version": "0.56.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -2257,6 +2257,202 @@
         }
       }
     },
+    "/v2/integrations/{integrationId}/monitoring/events": {
+      "post": {
+        "operationId": "queryMonitoringEventsV2",
+        "summary": "queryMonitoringEventsV2",
+        "description": "Query monitoring events from the unified erp_monitoring_v2 table.\nReturns all event types (inbound, outbound, file_proxy, etc.) in a single list.\nReplaces the separate v1 inbound-events and outbound-events endpoints.\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/QueryMonitoringEventsV2Request"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/QueryMonitoringEventsV2Response"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/integrations/{integrationId}/monitoring/stats": {
+      "post": {
+        "operationId": "getMonitoringStatsV2",
+        "summary": "getMonitoringStatsV2",
+        "description": "Get aggregated statistics from the unified erp_monitoring_v2 table.\nReturns combined metrics for all event types with optional breakdowns.\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/GetMonitoringStatsV2Request"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetMonitoringStatsV2Response"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/integrations/{integrationId}/monitoring/time-series": {
+      "post": {
+        "operationId": "getMonitoringTimeSeriesV2",
+        "summary": "getMonitoringTimeSeriesV2",
+        "description": "Get time-series aggregated event counts from the unified erp_monitoring_v2 table.\nReturns bucketed counts for chart rendering.\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/GetMonitoringTimeSeriesV2Request"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetMonitoringTimeSeriesV2Response"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/integrations/{integrationId}/monitoring/events/{eventId}/associated": {
+      "get": {
+        "operationId": "getAssociatedMonitoringEvents",
+        "summary": "getAssociatedMonitoringEvents",
+        "description": "Returns all monitoring events sharing the same event_id, ordered chronologically.\nAlso includes the original inbound event payload from erp_incoming_events if available.\nUsed to display a full event trace/timeline.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "eventId",
+            "in": "path",
+            "required": true,
+            "description": "The event ID to get associated events for",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetAssociatedMonitoringEventsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/integrations/secure-proxies": {
       "get": {
         "operationId": "listSecureProxies",
@@ -2472,6 +2668,176 @@
           }
         }
       }
+    },
+    "/v1/integrations/{integrationId}/generate-types-preview": {
+      "post": {
+        "operationId": "generateTypesPreview",
+        "summary": "Preview scaffolded types for a connector integration",
+        "description": "Analyses the JSONata mappings of all managed-call use cases in the integration and returns scaffolded type descriptors. The frontend uses these to show the type editor modal where developers fill in leaf types.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Scaffolded type preview",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GenerateTypesPreviewResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/generate-types": {
+      "post": {
+        "operationId": "generateTypes",
+        "summary": "Generate a TypeScript npm package for a connector integration",
+        "description": "Generates a complete TypeScript npm package with typed interfaces for all managed-call use cases. This is a stateless operation that does not persist any changes. Use the commit-types endpoint to lock configurations after review.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GenerateTypesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Generated package",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GenerateTypesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/commit-types": {
+      "post": {
+        "operationId": "commitTypes",
+        "summary": "Commit generated types and lock use case configurations",
+        "description": "Commits the generated types by locking use case configurations and updating version tracking. Should be called after the user reviews and downloads the generated package.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CommitTypesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Types committed successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CommitTypesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -2843,6 +3209,50 @@
           },
           "auth": {
             "$ref": "#/components/schemas/ManagedCallAuth"
+          },
+          "types_versions": {
+            "type": "array",
+            "description": "History of generated type package versions",
+            "items": {
+              "type": "object",
+              "required": [
+                "version",
+                "package_name",
+                "generated_at",
+                "generated_by",
+                "status"
+              ],
+              "properties": {
+                "version": {
+                  "type": "string"
+                },
+                "package_name": {
+                  "type": "string"
+                },
+                "generated_at": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "generated_by": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "active",
+                    "deprecated"
+                  ]
+                }
+              }
+            }
+          },
+          "latest_types_version": {
+            "type": "string",
+            "description": "Latest active types package version"
+          },
+          "latest_types_package_name": {
+            "type": "string",
+            "description": "Latest active types package name"
           }
         }
       },
@@ -3836,6 +4246,13 @@
               },
               "configuration": {
                 "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              },
+              "type_annotations": {
+                "$ref": "#/components/schemas/TypeAnnotations"
+              },
+              "types_locked": {
+                "type": "boolean",
+                "description": "Whether types have been generated for this use case"
               }
             }
           }
@@ -4215,6 +4632,9 @@
               },
               "configuration": {
                 "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              },
+              "type_annotations": {
+                "$ref": "#/components/schemas/TypeAnnotations"
               }
             }
           }
@@ -4428,6 +4848,13 @@
               },
               "configuration": {
                 "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              },
+              "type_annotations": {
+                "$ref": "#/components/schemas/TypeAnnotations"
+              },
+              "types_locked": {
+                "type": "boolean",
+                "description": "Whether types have been generated for this use case"
               }
             }
           }
@@ -4481,6 +4908,14 @@
             },
             "readOnly": true,
             "description": "Domain whitelist for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script.\nSupports exact match (e.g., \"api.wemag.com\") and wildcard prefix (e.g., \"*.wemag.com\").\n"
+          },
+          "allowed_ips": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "readOnly": true,
+            "description": "IP allowlist (CIDR notation) for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script.\nRequired for secure_link mode. All DNS-resolved IPs must match at least one range.\nExample: [\"10.0.1.0/24\", \"192.168.1.0/24\"]\n"
           }
         }
       },
@@ -4521,6 +4956,12 @@
               "type": "string"
             }
           },
+          "allowed_ips": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
           "integration_id": {
             "type": "string",
             "format": "uuid"
@@ -4618,108 +5059,375 @@
           "operation": {
             "$ref": "#/components/schemas/ManagedCallOperation"
           },
-          "request_mapping": {
+          "request_mapping": {
+            "type": "string",
+            "description": "JSONata expression for outbound body transformation"
+          },
+          "response_mapping": {
+            "type": "string",
+            "description": "JSONata expression for inbound response transformation"
+          },
+          "inbound_use_case_slug": {
+            "type": "string",
+            "description": "Slug of the inbound use case to route responses to for async entity processing.\nWhen set, the managed call response is queued to the inbound pipeline and processed\nusing the referenced inbound use case's mapping configuration.\n"
+          }
+        }
+      },
+      "ManagedCallOperation": {
+        "type": "object",
+        "required": [
+          "method",
+          "path"
+        ],
+        "description": "HTTP operation configuration for managed calls",
+        "properties": {
+          "method": {
+            "type": "string",
+            "enum": [
+              "GET",
+              "POST",
+              "PUT",
+              "PATCH",
+              "DELETE"
+            ]
+          },
+          "path": {
+            "type": "string",
+            "description": "URL path template with {{variable}} interpolation"
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "query_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ManagedCallExecuteRequest": {
+        "type": "object",
+        "required": [
+          "integration_id"
+        ],
+        "properties": {
+          "integration_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Integration ID"
+          },
+          "payload": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Request payload for the managed call operation"
+          },
+          "correlation_id": {
+            "type": "string",
+            "description": "Correlation ID for tracing related events (auto-generated if not provided)"
+          }
+        }
+      },
+      "ManagedCallExecuteResponse": {
+        "description": "The response from a managed call execution.\nOn success, returns the JSONata-mapped response data directly (no wrapper).\nThe shape is entirely defined by your response_mapping JSONata expression.\nIf no response_mapping is configured, returns the raw external API response.\nCheck the X-Inbound-Event-Id header for inbound pipeline tracking when inbound routing is configured.\n",
+        "additionalProperties": true
+      },
+      "ManagedCallErrorResponse": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "Error code (e.g., EXTERNAL_API_ERROR, SSRF_BLOCKED, MANAGED_CALL_EXECUTION_ERROR)"
+              },
+              "message": {
+                "type": "string",
+                "description": "Human-readable error message"
+              },
+              "details": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "Additional error details (e.g., status code and body for external API errors)"
+              }
+            }
+          }
+        }
+      },
+      "TypeAnnotations": {
+        "type": "object",
+        "description": "Developer-provided type annotations for a use case's request and response fields",
+        "properties": {
+          "request": {
+            "type": "object",
+            "description": "Type annotations for request fields, keyed by dot-path (e.g., \"vendors[].id\" -> \"string\")",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "response": {
+            "type": "object",
+            "description": "Type annotations for response fields",
+            "additionalProperties": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "TypeDescriptor": {
+        "type": "object",
+        "description": "Describes the inferred type shape of a JSONata expression",
+        "required": [
+          "kind"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "object",
+              "array",
+              "string",
+              "number",
+              "boolean",
+              "null",
+              "unknown",
+              "union"
+            ]
+          },
+          "properties": {
+            "type": "object",
+            "description": "For kind=object, the properties and their type descriptors",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/TypeDescriptor"
+            }
+          },
+          "items": {
+            "description": "For kind=array, the type of array items",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/TypeDescriptor"
+              }
+            ]
+          },
+          "source": {
+            "type": "string",
+            "description": "For kind=unknown, the JSONata path that produced this value"
+          },
+          "variants": {
+            "type": "array",
+            "description": "For kind=union, the variant types",
+            "items": {
+              "$ref": "#/components/schemas/TypeDescriptor"
+            }
+          }
+        }
+      },
+      "UseCaseTypePreview": {
+        "type": "object",
+        "description": "Scaffolded type descriptors for a single use case",
+        "required": [
+          "slug",
+          "request_shape",
+          "response_shape"
+        ],
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "request_shape": {
+            "$ref": "#/components/schemas/TypeDescriptor"
+          },
+          "response_shape": {
+            "$ref": "#/components/schemas/TypeDescriptor"
+          },
+          "existing_annotations": {
+            "$ref": "#/components/schemas/TypeAnnotations"
+          }
+        }
+      },
+      "GenerateTypesPreviewResponse": {
+        "type": "object",
+        "required": [
+          "use_cases"
+        ],
+        "properties": {
+          "integration_name": {
+            "type": "string"
+          },
+          "use_cases": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UseCaseTypePreview"
+            }
+          },
+          "previous_version": {
+            "type": "string",
+            "description": "Previously generated version, if any"
+          },
+          "suggested_version": {
+            "type": "string",
+            "description": "Suggested next version based on detected changes"
+          },
+          "suggested_bump": {
+            "type": "string",
+            "enum": [
+              "major",
+              "minor"
+            ]
+          },
+          "detected_changes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "slug",
+                "field",
+                "type",
+                "description"
+              ],
+              "properties": {
+                "slug": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "breaking",
+                    "non-breaking"
+                  ]
+                },
+                "description": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "GenerateTypesRequest": {
+        "type": "object",
+        "required": [
+          "package_name",
+          "version"
+        ],
+        "properties": {
+          "package_name": {
+            "type": "string",
+            "description": "npm package name",
+            "example": "@epilot/hems-cleverpv"
+          },
+          "version": {
             "type": "string",
-            "description": "JSONata expression for outbound body transformation"
+            "description": "Package version",
+            "example": "1.0.0"
           },
-          "response_mapping": {
+          "description": {
+            "type": "string"
+          },
+          "domain_package": {
             "type": "string",
-            "description": "JSONata expression for inbound response transformation"
+            "description": "Domain standard package to extend",
+            "example": "@epilot/hems"
           },
-          "inbound_use_case_slug": {
+          "domain_map_name": {
             "type": "string",
-            "description": "Slug of the inbound use case to route responses to for async entity processing.\nWhen set, the managed call response is queued to the inbound pipeline and processed\nusing the referenced inbound use case's mapping configuration.\n"
+            "description": "Name of the domain UseCaseMap to extend",
+            "example": "HemsUseCaseMap"
+          },
+          "annotations": {
+            "type": "object",
+            "description": "Type annotations per use case slug",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/TypeAnnotations"
+            }
           }
         }
       },
-      "ManagedCallOperation": {
+      "GenerateTypesResponse": {
         "type": "object",
         "required": [
-          "method",
-          "path"
+          "package_name",
+          "version",
+          "files"
         ],
-        "description": "HTTP operation configuration for managed calls",
         "properties": {
-          "method": {
-            "type": "string",
-            "enum": [
-              "GET",
-              "POST",
-              "PUT",
-              "PATCH",
-              "DELETE"
-            ]
+          "package_name": {
+            "type": "string"
           },
-          "path": {
-            "type": "string",
-            "description": "URL path template with {{variable}} interpolation"
+          "version": {
+            "type": "string"
           },
-          "headers": {
+          "files": {
             "type": "object",
+            "description": "Generated file contents keyed by file path",
             "additionalProperties": {
               "type": "string"
             }
           },
-          "query_params": {
-            "type": "object",
-            "additionalProperties": {
+          "warnings": {
+            "type": "array",
+            "items": {
               "type": "string"
             }
           }
         }
       },
-      "ManagedCallExecuteRequest": {
+      "CommitTypesRequest": {
         "type": "object",
         "required": [
-          "integration_id"
+          "package_name",
+          "version"
         ],
         "properties": {
-          "integration_id": {
+          "package_name": {
             "type": "string",
-            "format": "uuid",
-            "description": "Integration ID"
-          },
-          "payload": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "Request payload for the managed call operation"
+            "description": "npm package name",
+            "example": "@epilot/hems-cleverpv"
           },
-          "correlation_id": {
+          "version": {
             "type": "string",
-            "description": "Correlation ID for tracing related events (auto-generated if not provided)"
+            "description": "Package version",
+            "example": "1.0.0"
+          },
+          "annotations": {
+            "type": "object",
+            "description": "Type annotations per use case slug",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/TypeAnnotations"
+            }
           }
         }
       },
-      "ManagedCallExecuteResponse": {
-        "description": "The response from a managed call execution.\nOn success, returns the JSONata-mapped response data directly (no wrapper).\nThe shape is entirely defined by your response_mapping JSONata expression.\nIf no response_mapping is configured, returns the raw external API response.\nCheck the X-Inbound-Event-Id header for inbound pipeline tracking when inbound routing is configured.\n",
-        "additionalProperties": true
-      },
-      "ManagedCallErrorResponse": {
+      "CommitTypesResponse": {
         "type": "object",
         "required": [
-          "error"
+          "committed"
         ],
         "properties": {
-          "error": {
-            "type": "object",
-            "required": [
-              "code",
-              "message"
-            ],
-            "properties": {
-              "code": {
-                "type": "string",
-                "description": "Error code (e.g., EXTERNAL_API_ERROR, SSRF_BLOCKED, MANAGED_CALL_EXECUTION_ERROR)"
-              },
-              "message": {
-                "type": "string",
-                "description": "Human-readable error message"
-              },
-              "details": {
-                "type": "object",
-                "additionalProperties": true,
-                "description": "Additional error details (e.g., status code and body for external API errors)"
-              }
+          "committed": {
+            "type": "boolean"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
             }
           }
         }
@@ -6351,48 +7059,222 @@
           },
           "event_id": {
             "type": "string",
-            "description": "Unique event identifier"
+            "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"
+          },
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
+              "UPDATE",
+              "DELETE",
+              "TRIGGER"
+            ],
+            "description": "Type of event (optional for V3 events)"
+          },
+          "object_type": {
+            "type": "string",
+            "description": "Type of object being synced (e.g., 'contract', 'meter')"
+          },
+          "sync_type": {
+            "type": "string",
+            "enum": [
+              "entity",
+              "meter_reading",
+              "webhook",
+              "api_deprecation"
+            ],
+            "description": "Type of sync operation"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "success",
+              "error",
+              "skipped",
+              "warning"
+            ],
+            "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"
+            ],
+            "description": "Error category (when status=error)"
+          },
+          "processing_duration_ms": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Processing duration in milliseconds"
+          },
+          "received_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the event was received"
+          },
+          "completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When processing completed"
+          }
+        }
+      },
+      "QueryMonitoringEventsV2Request": {
+        "type": "object",
+        "properties": {
+          "use_case_id": {
+            "type": "string",
+            "description": "Filter by use case ID (UUID). Empty string matches \"General\" events."
+          },
+          "use_case_type": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
+            ],
+            "description": "Filter by use case type (replaces direction)"
+          },
+          "level": {
+            "type": "string",
+            "enum": [
+              "success",
+              "error",
+              "skipped",
+              "warning"
+            ],
+            "description": "Filter by event level"
+          },
+          "code": {
+            "type": "string",
+            "description": "Filter by taxonomy code (e.g. OAUTH2_TOKEN_FAILURE, HTTP_502)"
+          },
+          "event_id": {
+            "type": "string",
+            "description": "Filter by trigger/inbound event ID"
+          },
+          "correlation_id": {
+            "type": "string",
+            "description": "Filter by correlation ID for tracing"
+          },
+          "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 (from previous response's next_cursor)",
+            "properties": {
+              "created_at": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "id": {
+                "type": "string",
+                "format": "uuid"
+              }
+            }
+          }
+        }
+      },
+      "MonitoringEventV2": {
+        "type": "object",
+        "required": [
+          "id",
+          "org_id",
+          "integration_id",
+          "event_id",
+          "use_case_type",
+          "level",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique monitoring event ID"
           },
-          "correlation_id": {
+          "org_id": {
             "type": "string",
-            "nullable": true,
-            "description": "Correlation ID for tracing related events"
+            "description": "Organization ID"
           },
           "integration_id": {
             "type": "string",
-            "nullable": true,
             "description": "Integration ID"
           },
-          "use_case_id": {
+          "event_id": {
             "type": "string",
-            "nullable": true,
-            "description": "Use case ID"
+            "description": "Trigger/inbound event ID (groups related monitoring events)"
           },
-          "event_type": {
+          "correlation_id": {
             "type": "string",
-            "enum": [
-              "CREATE",
-              "UPDATE",
-              "DELETE",
-              "TRIGGER"
-            ],
-            "description": "Type of event (optional for V3 events)"
+            "description": "Correlation ID for tracing. Empty when unavailable."
           },
-          "object_type": {
+          "use_case_id": {
             "type": "string",
-            "description": "Type of object being synced (e.g., 'contract', 'meter')"
+            "description": "Use case ID. Empty for system-level events (\"General\")."
           },
-          "sync_type": {
+          "use_case_type": {
             "type": "string",
             "enum": [
-              "entity",
-              "meter_reading",
-              "webhook",
-              "api_deprecation"
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy",
+              ""
             ],
-            "description": "Type of sync operation"
+            "description": "Use case type. Empty for system-level events."
           },
-          "status": {
+          "level": {
             "type": "string",
             "enum": [
               "success",
@@ -6400,44 +7282,198 @@
               "skipped",
               "warning"
             ],
-            "description": "Processing status"
+            "description": "Event outcome level"
           },
-          "error_code": {
+          "code": {
             "type": "string",
-            "nullable": true,
-            "description": "Error code (when status=error)"
+            "description": "Taxonomy code (e.g. OAUTH2_TOKEN_FAILURE, HTTP_502). Empty for success."
           },
-          "error_message": {
+          "message": {
             "type": "string",
+            "description": "Human-readable message. Empty when not applicable."
+          },
+          "detail": {
+            "type": "object",
             "nullable": true,
-            "description": "Error message (when status=error)"
+            "additionalProperties": true,
+            "description": "Event-specific JSON data. Structure determined by `code`."
           },
-          "error_category": {
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the monitoring event was created"
+          }
+        }
+      },
+      "GetMonitoringStatsV2Request": {
+        "type": "object",
+        "properties": {
+          "from_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Start of the time range",
+            "example": "2025-01-01T00:00:00Z"
+          },
+          "to_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "End of the time range",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "use_case_type": {
             "type": "string",
-            "nullable": true,
             "enum": [
-              "validation",
-              "configuration",
-              "downstream_api",
-              "timeout",
-              "system"
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
             ],
-            "description": "Error category (when status=error)"
+            "description": "Filter stats by use case type"
           },
-          "processing_duration_ms": {
+          "group_by": {
+            "type": "string",
+            "enum": [
+              "use_case_id",
+              "use_case_type",
+              "level",
+              "code",
+              "date"
+            ],
+            "description": "Field to group the breakdown by"
+          }
+        }
+      },
+      "MonitoringStatsV2": {
+        "type": "object",
+        "required": [
+          "total_events",
+          "success_count",
+          "error_count",
+          "warning_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 error events"
+          },
+          "warning_count": {
             "type": "integer",
+            "description": "Number of warning events"
+          },
+          "skipped_count": {
+            "type": "integer",
+            "description": "Number of skipped events"
+          },
+          "ack_timeout_count": {
+            "type": "integer",
+            "description": "Number of ACK_TIMEOUT events (acknowledgement timed out)"
+          },
+          "success_rate": {
+            "type": "number",
+            "format": "float",
+            "description": "Success rate as percentage (0-100)"
+          },
+          "last_error_at": {
+            "type": "string",
+            "format": "date-time",
             "nullable": true,
-            "description": "Processing duration in milliseconds"
+            "description": "Timestamp of the most recent error"
           },
-          "received_at": {
+          "breakdown": {
+            "type": "array",
+            "description": "Statistics breakdown by requested group_by field",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "GetMonitoringTimeSeriesV2Request": {
+        "type": "object",
+        "required": [
+          "from_date",
+          "interval"
+        ],
+        "properties": {
+          "from_date": {
             "type": "string",
             "format": "date-time",
-            "description": "When the event was received"
+            "description": "Start of the time range (required)",
+            "example": "2025-01-01T00:00:00Z"
           },
-          "completed_at": {
+          "to_date": {
             "type": "string",
             "format": "date-time",
-            "description": "When processing completed"
+            "description": "End of the time range (defaults to now)",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "interval": {
+            "type": "string",
+            "enum": [
+              "5m",
+              "10m",
+              "30m",
+              "1h",
+              "3h",
+              "1d"
+            ],
+            "description": "Time bucket interval"
+          },
+          "use_case_type": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
+            ],
+            "description": "Filter by use case type"
+          }
+        }
+      },
+      "TimeSeriesBucketV2": {
+        "type": "object",
+        "required": [
+          "timestamp",
+          "total_count"
+        ],
+        "properties": {
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Bucket start timestamp"
+          },
+          "success_count": {
+            "type": "integer",
+            "description": "Number of successful events in the bucket"
+          },
+          "error_count": {
+            "type": "integer",
+            "description": "Number of error events in the bucket"
+          },
+          "warning_count": {
+            "type": "integer",
+            "description": "Number of warning events in the bucket"
+          },
+          "skipped_count": {
+            "type": "integer",
+            "description": "Number of skipped events in the bucket"
+          },
+          "total_count": {
+            "type": "integer",
+            "description": "Total events in the bucket"
           }
         }
       }
@@ -6774,6 +7810,117 @@
             }
           }
         }
+      },
+      "QueryMonitoringEventsV2Response": {
+        "description": "Monitoring events queried successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "data": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/MonitoringEventV2"
+                  },
+                  "description": "List of monitoring events"
+                },
+                "next_cursor": {
+                  "type": "object",
+                  "nullable": true,
+                  "description": "Cursor to fetch the next page. Null if no more results.",
+                  "properties": {
+                    "created_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "id": {
+                      "type": "string",
+                      "format": "uuid"
+                    }
+                  }
+                },
+                "has_more": {
+                  "type": "boolean",
+                  "description": "Indicates if more results are available"
+                }
+              }
+            }
+          }
+        }
+      },
+      "GetMonitoringStatsV2Response": {
+        "description": "Monitoring statistics retrieved successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/MonitoringStatsV2"
+            }
+          }
+        }
+      },
+      "GetMonitoringTimeSeriesV2Response": {
+        "description": "Time-series data retrieved successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "interval": {
+                  "type": "string",
+                  "enum": [
+                    "5m",
+                    "10m",
+                    "30m",
+                    "1h",
+                    "3h",
+                    "1d"
+                  ],
+                  "description": "The bucket interval"
+                },
+                "from_date": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "to_date": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "buckets": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/TimeSeriesBucketV2"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "GetAssociatedMonitoringEventsResponse": {
+        "description": "Associated monitoring events for the given event_id",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "monitoring_events": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/MonitoringEventV2"
+                  },
+                  "description": "All monitoring events sharing this event_id, ordered by created_at ASC"
+                },
+                "inbound_event": {
+                  "type": "object",
+                  "nullable": true,
+                  "additionalProperties": true,
+                  "description": "The original inbound event payload from erp_incoming_events, if available"
+                }
+              }
+            }
+          }
+        }
       }
     }
   }