@epilot/erp-integration-client 0.28.0 → 0.29.0

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.49.0",
+    "version": "0.50.1",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -21,6 +21,14 @@
     {
       "name": "monitoring",
       "description": "Monitoring and analytics endpoints"
+    },
+    {
+      "name": "managed-call",
+      "description": "Managed call endpoints for synchronous external API calls"
+    },
+    {
+      "name": "proxy",
+      "description": "Secure proxy endpoints"
     }
   ],
   "servers": [
@@ -2375,6 +2383,95 @@
           }
         }
       }
+    },
+    "/v1/managed-call/{slug}/execute": {
+      "post": {
+        "operationId": "managedCallExecute",
+        "summary": "Execute a managed call operation",
+        "description": "Execute a managed call operation synchronously. The slug in the path acts as the RPC method name.\nCalls an external partner API with JSONata mapping on both request and response.\n",
+        "tags": [
+          "managed-call"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "slug",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_-]*$"
+            },
+            "description": "Use case slug (acts as the RPC method name)"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ManagedCallExecuteRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Managed call executed successfully.\nThe response body is the JSONata-mapped result (or raw external API response if no mapping).\nIf inbound routing is configured, check X-Inbound-Event-Id header for tracking.\n",
+            "headers": {
+              "X-Inbound-Event-Id": {
+                "description": "Event ID for tracking inbound pipeline processing (only present when inbound routing is configured)",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManagedCallExecuteResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request (e.g., invalid URL blocked by SSRF protection)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManagedCallErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          },
+          "502": {
+            "description": "External API error (upstream service returned an error)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManagedCallErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -2510,12 +2607,14 @@
         "properties": {
           "event_name": {
             "type": "string",
-            "description": "Event name from integration mapping (e.g., business_partner, contract_account). Required when use_case_slug is not provided.\n"
+            "description": "Event name from integration mapping (e.g., business_partner, contract_account). Required when use_case_slug is not provided.\n",
+            "example": "business_partner"
           },
           "timestamp": {
             "type": "string",
             "format": "date-time",
-            "description": "Timestamp when the event occurred"
+            "description": "Timestamp when the event occurred",
+            "example": "2025-05-01T08:30:00Z"
           },
           "format": {
             "type": "string",
@@ -2524,7 +2623,8 @@
               "xml"
             ],
             "default": "json",
-            "description": "Format of the payload data"
+            "description": "Format of the payload data",
+            "example": "json"
           },
           "payload": {
             "oneOf": [
@@ -2540,14 +2640,16 @@
                 "additionalProperties": true
               }
             ],
-            "description": "The object data payload - can be either a serialized string or a direct JSON object"
+            "description": "The object data payload - can be either a serialized string or a direct JSON object",
+            "example": "{\"id\":\"BP10001\",\"name\":\"Acme Corporation\",\"type\":\"organization\",\"tax_id\":\"DE123456789\",\"status\":\"active\"}"
           },
           "use_case_slug": {
             "type": "string",
             "pattern": "^[a-z0-9][a-z0-9_-]*$",
             "minLength": 1,
             "maxLength": 255,
-            "description": "Recommended. Use case slug for routing this event to the correct use case configuration. If provided, takes precedence over event_name for use case lookup. Preferred over event_name-based routing as slugs are portable across environments.\n"
+            "description": "Recommended. Use case slug for routing this event to the correct use case configuration. If provided, takes precedence over event_name for use case lookup. Preferred over event_name-based routing as slugs are portable across environments.\n",
+            "example": "business_partner"
           },
           "deduplication_id": {
             "type": "string",
@@ -2712,6 +2814,107 @@
           },
           "settings": {
             "$ref": "#/components/schemas/IntegrationSettings"
+          },
+          "integration_type": {
+            "type": "string",
+            "enum": [
+              "erp",
+              "connector"
+            ],
+            "default": "erp",
+            "description": "Type of integration. \"erp\" is the ERP integration with inbound/outbound use cases. \"connector\" is for complex proxy integrations with external APIs.\n"
+          },
+          "connector_config": {
+            "$ref": "#/components/schemas/ConnectorConfig"
+          },
+          "protected": {
+            "type": "boolean",
+            "description": "If true, integration is displayed in read-only mode in the UI to discourage changes"
+          }
+        }
+      },
+      "ConnectorConfig": {
+        "type": "object",
+        "description": "Shared configuration for connector-type integrations",
+        "properties": {
+          "base_url": {
+            "type": "string",
+            "description": "Base URL for the partner API"
+          },
+          "auth": {
+            "$ref": "#/components/schemas/ManagedCallAuth"
+          }
+        }
+      },
+      "ManagedCallAuth": {
+        "type": "object",
+        "description": "Authentication configuration for managed call requests",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "oauth2_client_credentials",
+              "api_key",
+              "bearer"
+            ],
+            "description": "Authentication type"
+          },
+          "token_url": {
+            "type": "string",
+            "description": "OAuth2 token URL. Can be plain text or {{env.key}} reference."
+          },
+          "client_id": {
+            "type": "string",
+            "description": "OAuth2 client ID. Can be plain text or {{env.key}} reference."
+          },
+          "client_secret": {
+            "type": "string",
+            "description": "OAuth2 client secret. Must be an {{env.key}} reference (secret)."
+          },
+          "scope": {
+            "type": "string",
+            "description": "OAuth2 scope"
+          },
+          "audience": {
+            "type": "string",
+            "description": "OAuth2 audience parameter (e.g. for Auth0, Azure AD). Can be plain text or {{env.key}} reference."
+          },
+          "resource": {
+            "type": "string",
+            "description": "OAuth2 resource parameter (e.g. for Azure AD). Can be plain text or {{env.key}} reference."
+          },
+          "body_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional key-value pairs for the OAuth2 token request body. Values can be {{env.key}} references."
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional headers for the OAuth2 token request. Values can be {{env.key}} references."
+          },
+          "query_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional query parameters for the OAuth2 token URL. Values can be {{env.key}} references."
+          },
+          "api_key_header": {
+            "type": "string",
+            "description": "Header name for API key auth (default X-API-Key)"
+          },
+          "api_key": {
+            "type": "string",
+            "description": "API key value. Must be an {{env.key}} reference (secret)."
+          },
+          "token": {
+            "type": "string",
+            "description": "Bearer token value. Must be an {{env.key}} reference (secret)."
           }
         }
       },
@@ -3294,6 +3497,9 @@
           {
             "$ref": "#/components/schemas/EmbeddedFileProxyUseCaseRequest"
           },
+          {
+            "$ref": "#/components/schemas/EmbeddedManagedCallUseCaseRequest"
+          },
           {
             "$ref": "#/components/schemas/EmbeddedSecureProxyUseCaseRequest"
           }
@@ -3304,6 +3510,7 @@
             "inbound": "#/components/schemas/EmbeddedInboundUseCaseRequest",
             "outbound": "#/components/schemas/EmbeddedOutboundUseCaseRequest",
             "file_proxy": "#/components/schemas/EmbeddedFileProxyUseCaseRequest",
+            "managed_call": "#/components/schemas/EmbeddedManagedCallUseCaseRequest",
             "secure_proxy": "#/components/schemas/EmbeddedSecureProxyUseCaseRequest"
           }
         }
@@ -3420,6 +3627,31 @@
           }
         ]
       },
+      "EmbeddedManagedCallUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              }
+            }
+          }
+        ]
+      },
       "EmbeddedSecureProxyUseCaseRequest": {
         "allOf": [
           {
@@ -3484,6 +3716,7 @@
               "inbound",
               "outbound",
               "file_proxy",
+              "managed_call",
               "secure_proxy"
             ],
             "description": "Use case type"
@@ -3583,6 +3816,31 @@
           }
         ]
       },
+      "ManagedCallUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              }
+            }
+          }
+        ]
+      },
       "SecureProxyUseCase": {
         "allOf": [
           {
@@ -3619,6 +3877,9 @@
           {
             "$ref": "#/components/schemas/FileProxyUseCase"
           },
+          {
+            "$ref": "#/components/schemas/ManagedCallUseCase"
+          },
           {
             "$ref": "#/components/schemas/SecureProxyUseCase"
           }
@@ -3629,6 +3890,7 @@
             "inbound": "#/components/schemas/InboundUseCase",
             "outbound": "#/components/schemas/OutboundUseCase",
             "file_proxy": "#/components/schemas/FileProxyUseCase",
+            "managed_call": "#/components/schemas/ManagedCallUseCase",
             "secure_proxy": "#/components/schemas/SecureProxyUseCase"
           }
         }
@@ -3644,6 +3906,9 @@
           {
             "$ref": "#/components/schemas/CreateFileProxyUseCaseRequest"
           },
+          {
+            "$ref": "#/components/schemas/CreateManagedCallUseCaseRequest"
+          },
           {
             "$ref": "#/components/schemas/CreateSecureProxyUseCaseRequest"
           }
@@ -3654,6 +3919,7 @@
             "inbound": "#/components/schemas/CreateInboundUseCaseRequest",
             "outbound": "#/components/schemas/CreateOutboundUseCaseRequest",
             "file_proxy": "#/components/schemas/CreateFileProxyUseCaseRequest",
+            "managed_call": "#/components/schemas/CreateManagedCallUseCaseRequest",
             "secure_proxy": "#/components/schemas/CreateSecureProxyUseCaseRequest"
           }
         }
@@ -3760,6 +4026,31 @@
           }
         ]
       },
+      "CreateManagedCallUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              }
+            }
+          }
+        ]
+      },
       "CreateSecureProxyUseCaseRequest": {
         "allOf": [
           {
@@ -3796,6 +4087,9 @@
           {
             "$ref": "#/components/schemas/UpdateFileProxyUseCaseRequest"
           },
+          {
+            "$ref": "#/components/schemas/UpdateManagedCallUseCaseRequest"
+          },
           {
             "$ref": "#/components/schemas/UpdateSecureProxyUseCaseRequest"
           }
@@ -3806,6 +4100,7 @@
             "inbound": "#/components/schemas/UpdateInboundUseCaseRequest",
             "outbound": "#/components/schemas/UpdateOutboundUseCaseRequest",
             "file_proxy": "#/components/schemas/UpdateFileProxyUseCaseRequest",
+            "managed_call": "#/components/schemas/UpdateManagedCallUseCaseRequest",
             "secure_proxy": "#/components/schemas/UpdateSecureProxyUseCaseRequest"
           }
         }
@@ -3903,6 +4198,28 @@
           }
         ]
       },
+      "UpdateManagedCallUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              }
+            }
+          }
+        ]
+      },
       "UpdateSecureProxyUseCaseRequest": {
         "allOf": [
           {
@@ -3936,6 +4253,9 @@
           {
             "$ref": "#/components/schemas/FileProxyUseCaseHistoryEntry"
           },
+          {
+            "$ref": "#/components/schemas/ManagedCallUseCaseHistoryEntry"
+          },
           {
             "$ref": "#/components/schemas/SecureProxyUseCaseHistoryEntry"
           }
@@ -3946,6 +4266,7 @@
             "inbound": "#/components/schemas/InboundUseCaseHistoryEntry",
             "outbound": "#/components/schemas/OutboundUseCaseHistoryEntry",
             "file_proxy": "#/components/schemas/FileProxyUseCaseHistoryEntry",
+            "managed_call": "#/components/schemas/ManagedCallUseCaseHistoryEntry",
             "secure_proxy": "#/components/schemas/SecureProxyUseCaseHistoryEntry"
           }
         }
@@ -4087,6 +4408,31 @@
           }
         ]
       },
+      "ManagedCallUseCaseHistoryEntry": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              }
+            }
+          }
+        ]
+      },
       "SecureProxyUseCaseHistoryEntry": {
         "allOf": [
           {
@@ -4262,6 +4608,122 @@
           }
         }
       },
+      "ManagedCallOperationConfig": {
+        "type": "object",
+        "required": [
+          "operation"
+        ],
+        "description": "Configuration for managed_call use cases. Defines a single API operation with JSONata mapping.",
+        "properties": {
+          "operation": {
+            "$ref": "#/components/schemas/ManagedCallOperation"
+          },
+          "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)"
+              }
+            }
+          }
+        }
+      },
       "FileProxyUseCaseConfiguration": {
         "type": "object",
         "required": [
@@ -4271,8 +4733,12 @@
         "description": "Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.\n\nThe file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.\nThe `orgId` is included in the signed URL to establish organization context without requiring authentication.\nAdditional use-case-specific parameters are declared in the `params` array.\n",
         "properties": {
           "secure_proxy": {
-            "$ref": "#/components/schemas/FileProxySecureProxyAttachment",
-            "description": "Optional secure proxy attachment for routing all outbound file proxy requests.\nOnly `use_case_slug` is supported and the referenced secure_proxy use case\nmust belong to the same integration.\n"
+            "description": "Optional secure proxy attachment for routing all outbound file proxy requests.\nOnly `use_case_slug` is supported and the referenced secure_proxy use case\nmust belong to the same integration.\n",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/FileProxySecureProxyAttachment"
+              }
+            ]
           },
           "auth": {
             "$ref": "#/components/schemas/FileProxyAuth"
@@ -6007,6 +6473,16 @@
           }
         }
       },
+      "Forbidden": {
+        "description": "Forbidden - insufficient permissions",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponseBase"
+            }
+          }
+        }
+      },
       "InternalServerError": {
         "description": "Internal Server Error",
         "content": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/erp-integration-client",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Client library for ePilot ERP Integration API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(pnpm install:*)"
-    ]
-  }
-}