@epilot/erp-integration-client 0.15.1 → 0.15.3

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.18.0",
+    "version": "0.24.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -17,6 +17,10 @@
     {
       "name": "integrations",
       "description": "Integration and Use Case management endpoints"
+    },
+    {
+      "name": "monitoring",
+      "description": "Monitoring and analytics endpoints"
     }
   ],
   "servers": [
@@ -1594,6 +1598,45 @@
             "$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}": {
@@ -1639,9 +1682,9 @@
         }
       },
       "put": {
-        "operationId": "upsertIntegrationV2",
-        "summary": "upsertIntegrationV2",
-        "description": "Create or update an integration with embedded use cases (upsert).\nIf the integration does not exist, it will be created with the specified ID.\nIf it exists, it will be 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\nThis is ideal for Infrastructure-as-Code tools like Terraform.\n",
+        "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"
         ],
@@ -1669,7 +1712,7 @@
         },
         "responses": {
           "200": {
-            "description": "Integration created or updated successfully with use cases",
+            "description": "Integration updated successfully with use cases",
             "content": {
               "application/json": {
                 "schema": {
@@ -1684,6 +1727,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "404": {
+            "description": "Integration not found"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -1860,6 +1906,156 @@
           }
         }
       }
+    },
+    "/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"
+            }
+          }
+        ],
+        "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"
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/monitoring/access-logs": {
+      "post": {
+        "operationId": "queryAccessLogs",
+        "summary": "queryAccessLogs",
+        "description": "Query API access logs for a specific integration's organization.\nReturns access token usage analytics filtered by user_id (access token).\nSupports infinite scroll pagination with cursor-based navigation.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID (used for tenant authorization)",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/QueryAccessLogsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/QueryAccessLogsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -1906,7 +2102,7 @@
           },
           "object_type": {
             "type": "string",
-            "description": "Type of the object being updated (business_partner, contract_account, etc.)"
+            "description": "Type of the object being updated (business_partner, contract_account, etc.). Corresponds to \"Event Name\" from the integration UI."
           },
           "timestamp": {
             "type": "string",
@@ -2192,7 +2388,7 @@
           }
         }
       },
-      "UseCase": {
+      "UseCaseBase": {
         "type": "object",
         "required": [
           "id",
@@ -2227,8 +2423,7 @@
             "description": "Use case type"
           },
           "enabled": {
-            "type": "boolean",
-            "description": "Whether the use case is enabled"
+            "type": "boolean"
           },
           "change_description": {
             "type": "string",
@@ -2245,8 +2440,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"
           },
@@ -2262,42 +2509,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": [
           {
@@ -3464,8 +3675,475 @@
             }
           }
         }
-      }
-    },
+      },
+      "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"
+              }
+            }
+          }
+        }
+      },
+      "QueryAccessLogsRequest": {
+        "type": "object",
+        "required": [
+          "token_id"
+        ],
+        "properties": {
+          "token_id": {
+            "type": "string",
+            "description": "Filter by access token ID (e.g., 'api_5ZugdRXasLfWBypHi93Fk')",
+            "example": "api_5ZugdRXasLfWBypHi93Fk"
+          },
+          "service": {
+            "type": "string",
+            "description": "Filter by service name (e.g., 'entity', 'metering', 'submission-api')",
+            "example": "entity"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "GET",
+              "POST",
+              "PUT",
+              "PATCH",
+              "DELETE",
+              "OPTIONS",
+              "HEAD"
+            ],
+            "description": "Filter by HTTP method"
+          },
+          "path": {
+            "type": "string",
+            "description": "Filter by request path (partial match)",
+            "example": "/v1/entity"
+          },
+          "status": {
+            "type": "integer",
+            "description": "Filter by HTTP status code",
+            "example": 200
+          },
+          "from_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter logs from this date (inclusive)",
+            "example": "2025-01-01T00:00:00Z"
+          },
+          "to_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter logs 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 (infinite scroll)",
+            "properties": {
+              "timestamp": {
+                "type": "string",
+                "format": "date-time",
+                "description": "Timestamp from the last log entry in the previous page"
+              },
+              "request_id": {
+                "type": "string",
+                "description": "Request ID from the last log entry in the previous page"
+              }
+            }
+          }
+        }
+      },
+      "AccessLogEntry": {
+        "type": "object",
+        "properties": {
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the request was made"
+          },
+          "environment": {
+            "type": "string",
+            "description": "Environment (e.g., 'dev', 'prod')"
+          },
+          "service": {
+            "type": "string",
+            "description": "Service name (e.g., 'entity', 'metering')"
+          },
+          "request_id": {
+            "type": "string",
+            "description": "Unique request identifier"
+          },
+          "method": {
+            "type": "string",
+            "description": "HTTP method"
+          },
+          "path": {
+            "type": "string",
+            "description": "Request path"
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code"
+          },
+          "response_latency_ms": {
+            "type": "integer",
+            "description": "Response latency in milliseconds"
+          },
+          "response_length": {
+            "type": "integer",
+            "description": "Response body length in bytes"
+          },
+          "token_id": {
+            "type": "string",
+            "description": "Access token identifier"
+          },
+          "org_id": {
+            "type": "string",
+            "description": "Organization ID"
+          },
+          "origin": {
+            "type": "string",
+            "description": "Request origin header"
+          },
+          "source_ip": {
+            "type": "string",
+            "description": "Client IP address"
+          }
+        }
+      },
+      "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",
+          "total_correlations",
+          "success_count",
+          "error_count",
+          "skipped_count"
+        ],
+        "properties": {
+          "total_events": {
+            "type": "integer",
+            "description": "Total number of events in the period"
+          },
+          "total_correlations": {
+            "type": "integer",
+            "description": "Total number of unique correlation IDs (a correlation_id groups multiple event_ids)"
+          },
+          "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": {
       "BadRequest": {
         "description": "Bad request",
@@ -3507,6 +4185,90 @@
           }
         }
       },
+      "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"
+            }
+          }
+        }
+      },
+      "QueryAccessLogsResponse": {
+        "description": "Access logs queried successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "data": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/AccessLogEntry"
+                  },
+                  "description": "List of access log entries"
+                },
+                "next_cursor": {
+                  "type": "object",
+                  "nullable": true,
+                  "description": "Cursor to fetch the next page. Null if no more results.",
+                  "properties": {
+                    "timestamp": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "request_id": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "has_more": {
+                  "type": "boolean",
+                  "description": "Indicates if more results are available"
+                }
+              }
+            }
+          }
+        }
+      },
       "ReplayEventsResponse": {
         "description": "Events replay initiated",
         "content": {