# Integration Toolkit API TypeScript SDK client for the epilot Integration Toolkit API: usage with @epilot/sdk, all operations and schemas. - **Base URL:** `https://integration-toolkit.sls.epilot.io` - **Full API Docs:** [https://docs.epilot.io/api/integration-toolkit](https://docs.epilot.io/api/integration-toolkit) ## Usage ```ts import { epilot } from '@epilot/sdk' epilot.authorize(() => '') const { data } = await epilot.integrationToolkit.acknowledgeTracking(...) ``` ### Tree-shakeable import ```ts import { getClient, authorize } from '@epilot/sdk/integration-toolkit' const integrationToolkitClient = getClient() authorize(integrationToolkitClient, () => '') const { data } = await integrationToolkitClient.acknowledgeTracking(...) ``` ## Operations **erp** - [`acknowledgeTracking`](#acknowledgetracking) - [`triggerErp`](#triggererp) - [`processErpUpdatesEventsV3`](#processerpupdateseventsv3) - [`queryErpUpdateEvents`](#queryerpupdateevents) - [`getErpUpdateEvent`](#geterpupdateevent) - [`listErpUpdateCorrelations`](#listerpupdatecorrelations) - [`simulateMappingV2`](#simulatemappingv2) - [`simulateDirect`](#simulatedirect) - [`simulateMapping`](#simulatemapping) **integrations** - [`listIntegrations`](#listintegrations) - [`createIntegration`](#createintegration) - [`getIntegration`](#getintegration) - [`updateIntegration`](#updateintegration) - [`deleteIntegration`](#deleteintegration) - [`queryEvents`](#queryevents) - [`replayEvents`](#replayevents) - [`listUseCases`](#listusecases) - [`createUseCase`](#createusecase) - [`getUseCase`](#getusecase) - [`updateUseCase`](#updateusecase) - [`deleteUseCase`](#deleteusecase) - [`listUseCaseHistory`](#listusecasehistory) - [`listDocumentationPages`](#listdocumentationpages) - [`getDocumentationPage`](#getdocumentationpage) - [`upsertDocumentationPage`](#upsertdocumentationpage) - [`deleteDocumentationPage`](#deletedocumentationpage) - [`listIntegrationsV2`](#listintegrationsv2) - [`createIntegrationV2`](#createintegrationv2) - [`getIntegrationV2`](#getintegrationv2) - [`updateIntegrationV2`](#updateintegrationv2) - [`deleteIntegrationV2`](#deleteintegrationv2) - [`listNotificationHistory`](#listnotificationhistory) - [`testSendNotification`](#testsendnotification) - [`getNotificationStatus`](#getnotificationstatus) - [`getSecureProxyWhitelist`](#getsecureproxywhitelist) - [`updateSecureProxyWhitelist`](#updatesecureproxywhitelist) - [`listSecureProxyWhitelistHistory`](#listsecureproxywhitelisthistory) - [`setIntegrationAppMapping`](#setintegrationappmapping) - [`deleteIntegrationAppMapping`](#deleteintegrationappmapping) - [`getOutboundStatus`](#getoutboundstatus) - [`getEntitySyncStatus`](#getentitysyncstatus) - [`pollOutboundMessages`](#polloutboundmessages) - [`ackOutboundMessages`](#ackoutboundmessages) - [`listOutboundDlqMessages`](#listoutbounddlqmessages) - [`redriveOutboundDlqMessages`](#redriveoutbounddlqmessages) - [`unblockOutboundStream`](#unblockoutboundstream) - [`simulateOutboundMapping`](#simulateoutboundmapping) - [`listSecureProxies`](#listsecureproxies) - [`generateTypesPreview`](#generatetypespreview) - [`generateTypes`](#generatetypes) - [`commitTypes`](#committypes) **monitoring** - [`queryAccessLogs`](#queryaccesslogs) - [`queryMonitoringEventsV2`](#querymonitoringeventsv2) - [`getMonitoringStatsV2`](#getmonitoringstatsv2) - [`getMonitoringTimeSeriesV2`](#getmonitoringtimeseriesv2) - [`getAssociatedMonitoringEvents`](#getassociatedmonitoringevents) - [`ingestExternalMonitoringEvents`](#ingestexternalmonitoringevents) - [`getMonitoringTraceByCorrelation`](#getmonitoringtracebycorrelation) - [`getMonitoringRunCompletionV2`](#getmonitoringruncompletionv2) **proxy** - [`secureProxy`](#secureproxy) **managed-call** - [`managedCallExecute`](#managedcallexecute) **erp-imports** - [`createErpImport`](#createerpimport) - [`listErpImports`](#listerpimports) - [`getErpImport`](#geterpimport) - [`deleteErpImport`](#deleteerpimport) - [`getErpImportPreview`](#geterpimportpreview) - [`downloadErpImportFile`](#downloaderpimportfile) - [`validateErpImport`](#validateerpimport) - [`suggestErpImportUseCases`](#suggesterpimportusecases) - [`executeErpImport`](#executeerpimport) - [`abortErpImport`](#aborterpimport) **Schemas** - [`S3Reference`](#s3reference) - [`CreateErpImportRequest`](#createerpimportrequest) - [`ValidateErpImportRequest`](#validateerpimportrequest) - [`ErpImportUseCaseSuggestion`](#erpimportusecasesuggestion) - [`SuggestErpImportUseCasesResponse`](#suggesterpimportusecasesresponse) - [`ExecuteErpImportRequest`](#executeerpimportrequest) - [`ErpImportIssue`](#erpimportissue) - [`ErpImportValidation`](#erpimportvalidation) - [`ErpImportEntityDetail`](#erpimportentitydetail) - [`ErpImportProgress`](#erpimportprogress) - [`ErpImportError`](#erpimporterror) - [`ErpImportFilePreview`](#erpimportfilepreview) - [`ErpImportDownload`](#erpimportdownload) - [`CreateErpImportResponse`](#createerpimportresponse) - [`ErpImportJob`](#erpimportjob) - [`ErpImportList`](#erpimportlist) - [`NotificationHistoryItem`](#notificationhistoryitem) - [`NotificationHistoryResponse`](#notificationhistoryresponse) - [`TestNotificationRequest`](#testnotificationrequest) - [`TestNotificationResponse`](#testnotificationresponse) - [`NotificationStatusResponse`](#notificationstatusresponse) - [`NotificationRuleStatus`](#notificationrulestatus) - [`RuleBaselineStatus`](#rulebaselinestatus) - [`RuleBaselineBucket`](#rulebaselinebucket) - [`ErrorResponseBase`](#errorresponsebase) - [`ErpEvent`](#erpevent) - [`ErpUpdatesEventsV2Request`](#erpupdateseventsv2request) - [`ErpEventV3`](#erpeventv3) - [`ErpUpdatesEventsV3Request`](#erpupdateseventsv3request) - [`ErpUpdateProcessedEntity`](#erpupdateprocessedentity) - [`CorrelationCloseResult`](#correlationcloseresult) - [`ErpUpdateProcessingError`](#erpupdateprocessingerror) - [`ErpUpdateEventStatus`](#erpupdateeventstatus) - [`CorrelationUseCaseCounts`](#correlationusecasecounts) - [`CorrelationStatus`](#correlationstatus) - [`CorrelationWaitResult`](#correlationwaitresult) - [`CorrelationWaitBadRequest`](#correlationwaitbadrequest) - [`CorrelationStatusList`](#correlationstatuslist) - [`TriggerErpActionRequest`](#triggererpactionrequest) - [`TriggerWebhookResp`](#triggerwebhookresp) - [`IntegrationEditableFields`](#integrationeditablefields) - [`ConnectorConfig`](#connectorconfig) - [`ManagedCallAuth`](#managedcallauth) - [`Integration`](#integration) - [`CreateIntegrationRequest`](#createintegrationrequest) - [`UpdateIntegrationRequest`](#updateintegrationrequest) - [`IntegrationMap`](#integrationmap) - [`EnvironmentFieldConfig`](#environmentfieldconfig) - [`IntegrationSettings`](#integrationsettings) - [`AutoRefreshSettings`](#autorefreshsettings) - [`IntegrationNotificationConfig`](#integrationnotificationconfig) - [`NotificationRecipient`](#notificationrecipient) - [`NotificationChannelSet`](#notificationchannelset) - [`NotificationRule`](#notificationrule) - [`NotificationDigestConfig`](#notificationdigestconfig) - [`SetIntegrationAppMappingRequest`](#setintegrationappmappingrequest) - [`DeleteIntegrationAppMappingRequest`](#deleteintegrationappmappingrequest) - [`IntegrationAppMapping`](#integrationappmapping) - [`IntegrationWithUseCases`](#integrationwithusecases) - [`UpsertIntegrationWithUseCasesRequest`](#upsertintegrationwithusecasesrequest) - [`InboundIntegrationEventConfiguration`](#inboundintegrationeventconfiguration) - [`OutboundIntegrationEventConfiguration`](#outboundintegrationeventconfiguration) - [`IntegrationEntity`](#integrationentity) - [`IntegrationEntitySharing`](#integrationentitysharing) - [`IntegrationEntitySharingPartner`](#integrationentitysharingpartner) - [`IntegrationEntityConditional`](#integrationentityconditional) - [`IntegrationEntityFromRows`](#integrationentityfromrows) - [`MappedFieldValue`](#mappedfieldvalue) - [`IntegrationMeterReading`](#integrationmeterreading) - [`PruneScopeConfig`](#prunescopeconfig) - [`MeterReadingPruneScopeConfig`](#meterreadingprunescopeconfig) - [`MeterUniqueIdsConfig`](#meteruniqueidsconfig) - [`IntegrationEntityField`](#integrationentityfield) - [`FileProxyUrlParam`](#fileproxyurlparam) - [`FileProxyUrlParams`](#fileproxyurlparams) - [`FileProxyUrlConfig`](#fileproxyurlconfig) - [`PortalOrigin`](#portalorigin) - [`PortalRefFilter`](#portalreffilter) - [`PortalRefConfig`](#portalrefconfig) - [`EnvVarRefConfig`](#envvarrefconfig) - [`EmbeddedUseCaseRequest`](#embeddedusecaserequest) - [`EmbeddedUseCaseRequestBase`](#embeddedusecaserequestbase) - [`EmbeddedInboundUseCaseRequest`](#embeddedinboundusecaserequest) - [`EmbeddedOutboundUseCaseRequest`](#embeddedoutboundusecaserequest) - [`EmbeddedFileProxyUseCaseRequest`](#embeddedfileproxyusecaserequest) - [`EmbeddedManagedCallUseCaseRequest`](#embeddedmanagedcallusecaserequest) - [`EmbeddedSecureProxyUseCaseRequest`](#embeddedsecureproxyusecaserequest) - [`UseCaseBase`](#usecasebase) - [`InboundUseCase`](#inboundusecase) - [`OutboundUseCase`](#outboundusecase) - [`FileProxyUseCase`](#fileproxyusecase) - [`ManagedCallUseCase`](#managedcallusecase) - [`SecureProxyUseCase`](#secureproxyusecase) - [`UseCase`](#usecase) - [`CreateUseCaseRequest`](#createusecaserequest) - [`CreateUseCaseRequestBase`](#createusecaserequestbase) - [`CreateInboundUseCaseRequest`](#createinboundusecaserequest) - [`CreateOutboundUseCaseRequest`](#createoutboundusecaserequest) - [`CreateFileProxyUseCaseRequest`](#createfileproxyusecaserequest) - [`CreateManagedCallUseCaseRequest`](#createmanagedcallusecaserequest) - [`CreateSecureProxyUseCaseRequest`](#createsecureproxyusecaserequest) - [`UpdateUseCaseRequest`](#updateusecaserequest) - [`UpdateUseCaseRequestBase`](#updateusecaserequestbase) - [`UpdateInboundUseCaseRequest`](#updateinboundusecaserequest) - [`UpdateOutboundUseCaseRequest`](#updateoutboundusecaserequest) - [`UpdateFileProxyUseCaseRequest`](#updatefileproxyusecaserequest) - [`UpdateManagedCallUseCaseRequest`](#updatemanagedcallusecaserequest) - [`UpdateSecureProxyUseCaseRequest`](#updatesecureproxyusecaserequest) - [`UseCaseHistoryEntry`](#usecasehistoryentry) - [`UseCaseHistoryEntryBase`](#usecasehistoryentrybase) - [`InboundUseCaseHistoryEntry`](#inboundusecasehistoryentry) - [`OutboundUseCaseHistoryEntry`](#outboundusecasehistoryentry) - [`FileProxyUseCaseHistoryEntry`](#fileproxyusecasehistoryentry) - [`ManagedCallUseCaseHistoryEntry`](#managedcallusecasehistoryentry) - [`SecureProxyUseCaseHistoryEntry`](#secureproxyusecasehistoryentry) - [`SecureProxyUseCaseConfiguration`](#secureproxyusecaseconfiguration) - [`SecureProxyWhitelist`](#secureproxywhitelist) - [`SecureProxyWhitelistUpdate`](#secureproxywhitelistupdate) - [`SecureProxySummary`](#secureproxysummary) - [`SecureProxyRequest`](#secureproxyrequest) - [`SecureProxyResponse`](#secureproxyresponse) - [`SecureProxyUpstreamError`](#secureproxyupstreamerror) - [`ManagedCallOperationConfig`](#managedcalloperationconfig) - [`ManagedCallOperation`](#managedcalloperation) - [`ManagedCallExecuteRequest`](#managedcallexecuterequest) - [`ManagedCallExecuteResponse`](#managedcallexecuteresponse) - [`ManagedCallErrorResponse`](#managedcallerrorresponse) - [`TypeAnnotations`](#typeannotations) - [`TypeDescriptor`](#typedescriptor) - [`UseCaseTypePreview`](#usecasetypepreview) - [`GenerateTypesPreviewResponse`](#generatetypespreviewresponse) - [`GenerateTypesRequest`](#generatetypesrequest) - [`GenerateTypesResponse`](#generatetypesresponse) - [`CommitTypesRequest`](#committypesrequest) - [`CommitTypesResponse`](#committypesresponse) - [`FileProxyUseCaseConfiguration`](#fileproxyusecaseconfiguration) - [`FileProxySecureProxyAttachment`](#fileproxysecureproxyattachment) - [`FileProxyAuth`](#fileproxyauth) - [`FileProxyParam`](#fileproxyparam) - [`FileProxyStep`](#fileproxystep) - [`FileProxyFanOutConfig`](#fileproxyfanoutconfig) - [`FileProxyUploadConfig`](#fileproxyuploadconfig) - [`FileProxyResponseConfig`](#fileproxyresponseconfig) - [`MappingSimulationRequest`](#mappingsimulationrequest) - [`MappingSimulationV2Request`](#mappingsimulationv2request) - [`MappingSimulationResponse`](#mappingsimulationresponse) - [`MappingSimulationWarning`](#mappingsimulationwarning) - [`DirectPayload`](#directpayload) - [`DirectEntityOperation`](#directentityoperation) - [`DirectMeterReadingOperation`](#directmeterreadingoperation) - [`DirectRelationValue`](#directrelationvalue) - [`DirectRelationItem`](#directrelationitem) - [`DirectRelationRefValue`](#directrelationrefvalue) - [`DirectRelationRefItem`](#directrelationrefitem) - [`DirectSimulationRequest`](#directsimulationrequest) - [`DirectSimulationResponse`](#directsimulationresponse) - [`DirectSimulationError`](#directsimulationerror) - [`EntityUpdate`](#entityupdate) - [`MeterReadingUpdate`](#meterreadingupdate) - [`EntityPruneScopeUpdate`](#entityprunescopeupdate) - [`MeterReadingPruneScopeUpdate`](#meterreadingprunescopeupdate) - [`IntegrationConfigurationV1`](#integrationconfigurationv1) - [`IntegrationObjectV1`](#integrationobjectv1) - [`IntegrationFieldV1`](#integrationfieldv1) - [`IntegrationConfigurationV2`](#integrationconfigurationv2) - [`OutboundMapping`](#outboundmapping) - [`DeliveryConfig`](#deliveryconfig) - [`WebhookDeliveryConfig`](#webhookdeliveryconfig) - [`PollDeliveryConfig`](#polldeliveryconfig) - [`FileProxyDeliveryConfig`](#fileproxydeliveryconfig) - [`EntitySyncStatusResponse`](#entitysyncstatusresponse) - [`EntitySyncState`](#entitysyncstate) - [`OutboundStatusResponse`](#outboundstatusresponse) - [`OutboundUseCaseStatus`](#outboundusecasestatus) - [`OutboundFileProxyTargetStatus`](#outboundfileproxytargetstatus) - [`OutboundPollStatus`](#outboundpollstatus) - [`WebhookStatus`](#webhookstatus) - [`OutboundConflict`](#outboundconflict) - [`PollOutboundMessagesRequest`](#polloutboundmessagesrequest) - [`OutboundMessage`](#outboundmessage) - [`PollOutboundMessagesResponse`](#polloutboundmessagesresponse) - [`AckOutboundMessagesRequest`](#ackoutboundmessagesrequest) - [`AckResult`](#ackresult) - [`AckOutboundMessagesResponse`](#ackoutboundmessagesresponse) - [`OutboundDlqMessage`](#outbounddlqmessage) - [`OutboundDlqListResponse`](#outbounddlqlistresponse) - [`RedriveOutboundDlqRequest`](#redriveoutbounddlqrequest) - [`RedriveOutboundDlqResult`](#redriveoutbounddlqresult) - [`RedriveOutboundDlqResponse`](#redriveoutbounddlqresponse) - [`UnblockOutboundStreamRequest`](#unblockoutboundstreamrequest) - [`UnblockOutboundStreamResponse`](#unblockoutboundstreamresponse) - [`SimulateOutboundMappingRequest`](#simulateoutboundmappingrequest) - [`OutboundMappingSimulationError`](#outboundmappingsimulationerror) - [`SimulateOutboundMappingResponse`](#simulateoutboundmappingresponse) - [`RelationConfig`](#relationconfig) - [`RelationItemConfig`](#relationitemconfig) - [`RelationUniqueIdField`](#relationuniqueidfield) - [`RelationRefsConfig`](#relationrefsconfig) - [`RelationRefItemConfig`](#relationrefitemconfig) - [`RelationRefValueConfig`](#relationrefvalueconfig) - [`RepeatableFieldType`](#repeatablefieldtype) - [`ReplayEventsRequest`](#replayeventsrequest) - [`QueryEventsRequest`](#queryeventsrequest) - [`QueryInboundMonitoringEventsRequest`](#queryinboundmonitoringeventsrequest) - [`QueryAccessLogsRequest`](#queryaccesslogsrequest) - [`AccessLogEntry`](#accesslogentry) - [`GetMonitoringStatsRequest`](#getmonitoringstatsrequest) - [`GetMonitoringTimeSeriesRequest`](#getmonitoringtimeseriesrequest) - [`TimeSeriesBucket`](#timeseriesbucket) - [`QueryOutboundMonitoringEventsRequest`](#queryoutboundmonitoringeventsrequest) - [`OutboundMonitoringEvent`](#outboundmonitoringevent) - [`MonitoringStats`](#monitoringstats) - [`InboundMonitoringEvent`](#inboundmonitoringevent) - [`QueryMonitoringEventsV2Request`](#querymonitoringeventsv2request) - [`ExternalMonitoringSpan`](#externalmonitoringspan) - [`IngestExternalMonitoringEventsRequest`](#ingestexternalmonitoringeventsrequest) - [`IngestExternalMonitoringEventsResponse`](#ingestexternalmonitoringeventsresponse) - [`MonitoringTraceResponse`](#monitoringtraceresponse) - [`MonitoringCode`](#monitoringcode) - [`MonitoringEventV2`](#monitoringeventv2) - [`GetMonitoringStatsV2Request`](#getmonitoringstatsv2request) - [`GetMonitoringRunCompletionV2Request`](#getmonitoringruncompletionv2request) - [`MonitoringRunCompletionV2Response`](#monitoringruncompletionv2response) - [`MonitoringRunCompletionV2`](#monitoringruncompletionv2) - [`MonitoringRunEntriesV2`](#monitoringrunentriesv2) - [`MonitoringStatsV2`](#monitoringstatsv2) - [`GetMonitoringTimeSeriesV2Request`](#getmonitoringtimeseriesv2request) - [`TimeSeriesBreakdownItemV2`](#timeseriesbreakdownitemv2) - [`TimeSeriesBucketV2`](#timeseriesbucketv2) - [`DocumentationPageSummary`](#documentationpagesummary) - [`DocumentationPage`](#documentationpage) - [`UpsertDocumentationPageRequest`](#upsertdocumentationpagerequest) ### `acknowledgeTracking` Acknowledges an ERP tracking record by removing it from the tracking table, requires public authentication `POST /v1/erp/tracking/acknowledgement` ```ts const { data } = await client.acknowledgeTracking( null, { ack_id: 'string' }, ) ```
Response ```json { "message": "string" } ```
--- ### `triggerErp` Triggers the ERP integration process `POST /v1/erp/trigger` ```ts const { data } = await client.triggerErp( null, { execution_id: 'string', org_id: 'string', webhook_id: 'string', flow_id: 'string', created_at: '1970-01-01T00:00:00.000Z', action_id: 'string', flow_action_id: 'string', flow_name: 'string', activity_id: 'string', entity_id: 'string' }, ) ```
Response ```json { "status_code": "string", "message": "string", "body": {}, "code": "string", "status": "succeeded", "start_date": "string", "end_date": "string", "event_id": "string" } ```
--- ### `processErpUpdatesEventsV3` Handles updates from ERP systems using integration_id directly. This is the v3 version that removes the unused event_type field and renames object_type to event_name to align with the integration UI n `POST /v3/erp/updates/events` ```ts const { data } = await client.processErpUpdatesEventsV3( null, { integration_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', correlation_id: 'string', group_id: 'customer-42', interactive: true, correlation_complete: true, events: [ {}, {} ] }, ) ```
Response ```json { "correlation_id": "string", "correlation_close": { "outcome": "applied", "reasons": ["retry_requested"], "message": "string" }, "results": [ { "event_id": "string", "status": "success", "interactive": true, "lane": "interactive", "message": "string" } ] } ```
--- ### `queryErpUpdateEvents` Waits for the events of one correlation — the long poll behind interactive registration — and returns the correlation's summary. `GET /v3/erp/updates/events` ```ts const { data } = await client.queryErpUpdateEvents({ correlation_id: 'example', wait: 1, wait_for_entities: ['...'], wait_for_use_cases: ['...'], }) ```
Response ```json { "correlation_id": "string", "integration_id": "string", "closed": true, "closed_at": "1970-01-01T00:00:00.000Z", "complete": true, "completed_at": "1970-01-01T00:00:00.000Z", "events_received": 0, "events_done": 0, "late_events": 0, "first_ingested_at": "1970-01-01T00:00:00.000Z", "last_done_at": "1970-01-01T00:00:00.000Z", "use_cases": [ { "use_case_slug": "string", "received": 0, "done": 0, "error": 0 } ], "entities": [ { "slug": "contact", "_id": "string", "operation": "created", "unique_ids": { "reenumber": "4711" } } ], "entities_omitted": 0, "errors": [ { "code": "string", "message": "string", "event_id": "string", "occurred_at": "1970-01-01T00:00:00.000Z", "after_completion": true } ], "errors_total": 0, "completion": "requirements_met", "undecided_entity_requirements": ["contract[billing_account_number=4711]"] } ```
--- ### `getErpUpdateEvent` Returns one interactive event's processing record, without waiting. `GET /v3/erp/updates/events/{event_id}` ```ts const { data } = await client.getErpUpdateEvent({ event_id: 'example', }) ```
Response ```json { "event_id": "string", "correlation_id": "string", "integration_id": "string", "status": "accepted", "lane": "interactive", "use_case_id": "string", "use_case_slug": "string", "event_name": "string", "ingested_at": "1970-01-01T00:00:00.000Z", "mapped_at": "1970-01-01T00:00:00.000Z", "done_at": "1970-01-01T00:00:00.000Z", "writes_total": 0, "writes_done": 0, "entities": [ { "slug": "contact", "_id": "string", "operation": "created", "unique_ids": { "reenumber": "4711" } } ], "entities_omitted": 0, "errors": [ { "code": "string", "message": "string", "event_id": "string", "occurred_at": "1970-01-01T00:00:00.000Z", "after_completion": true } ], "errors_total": 0 } ```
--- ### `listErpUpdateCorrelations` Lists the organization's interactive correlations, newest first by the time their first event was ingested, with the same summary the correlation wait returns. `GET /v3/erp/updates/correlations` ```ts const { data } = await client.listErpUpdateCorrelations({ integration_id: 'example', limit: 1, cursor: 'example', }) ```
Response ```json { "results": [ { "correlation_id": "string", "integration_id": "string", "closed": true, "closed_at": "1970-01-01T00:00:00.000Z", "complete": true, "completed_at": "1970-01-01T00:00:00.000Z", "events_received": 0, "events_done": 0, "late_events": 0, "first_ingested_at": "1970-01-01T00:00:00.000Z", "last_done_at": "1970-01-01T00:00:00.000Z", "use_cases": [ { "use_case_slug": "string", "received": 0, "done": 0, "error": 0 } ], "entities": [ { "slug": "contact", "_id": "string", "operation": "created", "unique_ids": { "reenumber": "4711" } } ], "entities_omitted": 0, "errors": [ { "code": "string", "message": "string", "event_id": "string", "occurred_at": "1970-01-01T00:00:00.000Z", "after_completion": true } ], "errors_total": 0 } ], "next_cursor": "string", "horizon_days": 7 } ```
--- ### `simulateMappingV2` Test v2.0 mapping configuration by transforming a payload using the provided mapping rules without persisting data. `POST /v2/erp/updates/mapping_simulation` ```ts const { data } = await client.simulateMappingV2( null, { event_configuration: { direct: true, interactive: 'on_request', entities: [ { /* ... */ } ], meter_readings: [ { /* ... */ } ] }, format: 'json', payload: 'string' }, ) ```
Response ```json { "entity_updates": [ { "entity_slug": "string", "unique_identifiers": {}, "attributes": {}, "pricing": { "config": {}, "data": [ {} ] }, "sharing": {}, "mode": "upsert" } ], "meter_readings_updates": [ { "meter": { "$entity_unique_ids": {} }, "meter_counter": { "$entity_unique_ids": {} }, "attributes": {}, "mode": "upsert" } ], "prune_scope_updates": [ { "entity_slug": "string", "scope": { "scope_mode": "relations", "schema": "string", "unique_ids": {}, "query": {} }, "keep_unique_ids": [ {} ], "deletion_mode": "delete" } ], "meter_readings_prune_scope_updates": [ { "meter": { "$entity_unique_ids": {} }, "meter_counter": { "$entity_unique_ids": {} }, "keep_external_ids": ["string"], "source": "string" } ], "warnings": [ { "entity_schema": "string", "field": "string", "message": "string" } ] } ```
--- ### `simulateDirect` Dry run for direct-mode payloads: validates a `DirectPayload` against a `direct: true` use case configuration and previews the internal entity and meter reading updates the pipeline would apply — with `POST /v1/erp/updates/direct_simulation` ```ts const { data } = await client.simulateDirect( null, { event_configuration: { direct: true, interactive: 'on_request', entities: [ { /* ... */ } ], meter_readings: [ { /* ... */ } ] }, payload: 'string' }, ) ```
Response ```json { "valid": true, "errors": [ { "code": "DIRECT_PAYLOAD_INVALID", "message": "string", "operation_index": 0 } ], "warnings": [ { "entity_schema": "string", "field": "string", "message": "string" } ], "entity_updates": [ { "entity_slug": "string", "unique_identifiers": {}, "attributes": {}, "pricing": { "config": {}, "data": [ {} ] }, "sharing": {}, "mode": "upsert", "unique_identifiers_metadata": {} } ], "meter_reading_updates": [ { "meter": { "$entity_unique_ids": {} }, "meter_counter": { "$entity_unique_ids": {} }, "attributes": {}, "mode": "upsert", "_config": { "reading_matching": "external_id" } } ] } ```
--- ### `simulateMapping` Test mapping configuration by transforming a payload using the provided mapping rules without persisting data. `POST /v1/erp/updates/mapping_simulation` ```ts const { data } = await client.simulateMapping( null, { mapping_configuration: { version: '1.0', mapping: { objects: {} } }, object_type: 'string', format: 'json', payload: 'string' }, ) ```
Response ```json { "entity_updates": [ { "entity_slug": "string", "unique_identifiers": {}, "attributes": {}, "pricing": { "config": {}, "data": [ {} ] }, "sharing": {}, "mode": "upsert" } ], "meter_readings_updates": [ { "meter": { "$entity_unique_ids": {} }, "meter_counter": { "$entity_unique_ids": {} }, "attributes": {}, "mode": "upsert" } ], "prune_scope_updates": [ { "entity_slug": "string", "scope": { "scope_mode": "relations", "schema": "string", "unique_ids": {}, "query": {} }, "keep_unique_ids": [ {} ], "deletion_mode": "delete" } ], "meter_readings_prune_scope_updates": [ { "meter": { "$entity_unique_ids": {} }, "meter_counter": { "$entity_unique_ids": {} }, "keep_external_ids": ["string"], "source": "string" } ], "warnings": [ { "entity_schema": "string", "field": "string", "message": "string" } ] } ```
--- ### `listIntegrations` Retrieve all integrations for the authenticated organization `GET /v1/integrations` ```ts const { data } = await client.listIntegrations() ```
Response ```json { "integrations": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [], "maps": [], "settings": {}, "integration_type": "erp", "connector_config": {}, "protected": true, "_manifest": ["string"] } ] } ```
--- ### `createIntegration` Create a new integration configuration `POST /v1/integrations` ```ts const { data } = await client.createIntegration( null, { name: 'string', description: 'string', access_token_ids: ['string'], app_ids: ['string'], environment_config: [ { key: 'string', label: 'string', type: 'String', description: 'string', required: false, order: 0 } ], maps: [ { key: 'string', label: 'string', description: 'string', value: {} } ], settings: { autoRefresh: { enabled: false, freshnessThresholdMinutes: 1 }, notifications: { enabled: true, recipients: [ /* ... */ ], defaultChannels: { /* ... */ }, monitoredUseCases: ['string'], monitoredCodes: ['string'], rules: [ /* ... */ ], digest: { /* ... */ }, muteUntil: '1970-01-01T00:00:00.000Z' } }, integration_type: 'erp', connector_config: { base_url: 'string', auth: { type: 'oauth2_client_credentials', token_url: 'string', client_id: 'string', client_secret: 'string', scope: 'string', audience: 'string', resource: 'string', body_params: {}, headers: {}, query_params: {}, api_key_header: 'string', api_key: 'string', token: 'string' }, types_versions: [ { /* ... */ } ], latest_types_version: 'string', latest_types_package_name: 'string' }, protected: true, _manifest: ['string'] }, ) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [ { "key": "string", "label": "string", "type": "String", "description": "string", "required": false, "order": 0 } ], "maps": [ { "key": "string", "label": "string", "description": "string", "value": {} } ], "settings": { "autoRefresh": { "enabled": false, "freshnessThresholdMinutes": 1 }, "notifications": { "enabled": true, "recipients": [], "defaultChannels": {}, "monitoredUseCases": ["string"], "monitoredCodes": ["string"], "rules": [], "digest": {}, "muteUntil": "1970-01-01T00:00:00.000Z" } }, "integration_type": "erp", "connector_config": { "base_url": "string", "auth": { "type": "oauth2_client_credentials", "token_url": "string", "client_id": "string", "client_secret": "string", "scope": "string", "audience": "string", "resource": "string", "body_params": {}, "headers": {}, "query_params": {}, "api_key_header": "string", "api_key": "string", "token": "string" }, "types_versions": [ {} ], "latest_types_version": "string", "latest_types_package_name": "string" }, "protected": true, "_manifest": ["string"] } ```
--- ### `getIntegration` Retrieve a specific integration by its ID `GET /v1/integrations/{integrationId}` ```ts const { data } = await client.getIntegration({ integrationId: 'example', }) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [ { "key": "string", "label": "string", "type": "String", "description": "string", "required": false, "order": 0 } ], "maps": [ { "key": "string", "label": "string", "description": "string", "value": {} } ], "settings": { "autoRefresh": { "enabled": false, "freshnessThresholdMinutes": 1 }, "notifications": { "enabled": true, "recipients": [], "defaultChannels": {}, "monitoredUseCases": ["string"], "monitoredCodes": ["string"], "rules": [], "digest": {}, "muteUntil": "1970-01-01T00:00:00.000Z" } }, "integration_type": "erp", "connector_config": { "base_url": "string", "auth": { "type": "oauth2_client_credentials", "token_url": "string", "client_id": "string", "client_secret": "string", "scope": "string", "audience": "string", "resource": "string", "body_params": {}, "headers": {}, "query_params": {}, "api_key_header": "string", "api_key": "string", "token": "string" }, "types_versions": [ {} ], "latest_types_version": "string", "latest_types_package_name": "string" }, "protected": true, "_manifest": ["string"] } ```
--- ### `updateIntegration` Update an existing integration configuration `PUT /v1/integrations/{integrationId}` ```ts const { data } = await client.updateIntegration( { integrationId: 'example', }, {}, ) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [ { "key": "string", "label": "string", "type": "String", "description": "string", "required": false, "order": 0 } ], "maps": [ { "key": "string", "label": "string", "description": "string", "value": {} } ], "settings": { "autoRefresh": { "enabled": false, "freshnessThresholdMinutes": 1 }, "notifications": { "enabled": true, "recipients": [], "defaultChannels": {}, "monitoredUseCases": ["string"], "monitoredCodes": ["string"], "rules": [], "digest": {}, "muteUntil": "1970-01-01T00:00:00.000Z" } }, "integration_type": "erp", "connector_config": { "base_url": "string", "auth": { "type": "oauth2_client_credentials", "token_url": "string", "client_id": "string", "client_secret": "string", "scope": "string", "audience": "string", "resource": "string", "body_params": {}, "headers": {}, "query_params": {}, "api_key_header": "string", "api_key": "string", "token": "string" }, "types_versions": [ {} ], "latest_types_version": "string", "latest_types_package_name": "string" }, "protected": true, "_manifest": ["string"] } ```
--- ### `deleteIntegration` Delete an integration and all its use cases `DELETE /v1/integrations/{integrationId}` ```ts const { data } = await client.deleteIntegration({ integrationId: 'example', }) ```
Response ```json { "message": "string" } ```
--- ### `queryEvents` Query events for a specific integration `POST /v1/integrations/{integrationId}/events` ```ts const { data } = await client.queryEvents( { integrationId: 'example', }, { event_id: 'string', event_type: 'CREATE', correlation_id: 'string', object_type: 'string', event_name: 'string', use_case_id: 'string', limit: 25, cursor: { event_time: '2025-10-31T12:34:56Z', event_id: 'evt_1234567890abcdef' } }, ) ```
Response ```json { "data": [ { "event_type": "CREATE", "object_type": "string", "timestamp": "1970-01-01T00:00:00.000Z", "format": "json", "payload": "string", "deduplication_id": "evt-2025-05-01-12345-create-bp", "correlation_id": "bp-8f3a2c-7d4e-4b1a-9c2f-1e6d5a4b3c21", "use_case_id": "string" } ], "next_cursor": { "event_time": "2025-10-31T12:34:56Z", "event_id": "evt_1234567890abcdef" }, "has_more": true } ```
--- ### `replayEvents` Replay one or more events for a specific integration. Events will be re-processed with their original payloads but with a new correlation ID for traceability. `POST /v1/integrations/{integrationId}/events/replay` ```ts const { data } = await client.replayEvents( { integrationId: 'example', }, { event_ids: ['string'] }, ) ```
Response ```json { "replayed": 2, "results": [ { "event_id": "string", "status": "success", "replay_event_id": "string", "message": "string" } ], "event_ids": ["string"] } ```
--- ### `listUseCases` Retrieve all use cases for a specific integration `GET /v1/integrations/{integrationId}/use-cases` ```ts const { data } = await client.listUseCases({ integrationId: 'example', }) ```
Response ```json { "use_cases": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": {} } ] } ```
--- ### `createUseCase` Create a new use case for an integration `POST /v1/integrations/{integrationId}/use-cases` ```ts const { data } = await client.createUseCase( { integrationId: 'example', }, { name: 'string', slug: 'string', enabled: true, type: 'inbound', configuration: { direct: true, interactive: 'on_request', entities: [ { /* ... */ } ], meter_readings: [ { /* ... */ } ] } }, ) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": { "direct": true, "interactive": "on_request", "entities": [ {} ], "meter_readings": [ {} ] } } ```
--- ### `getUseCase` Retrieve a specific use case by its ID `GET /v1/integrations/{integrationId}/use-cases/{useCaseId}` ```ts const { data } = await client.getUseCase({ integrationId: 'example', useCaseId: 'example', }) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": { "direct": true, "interactive": "on_request", "entities": [ {} ], "meter_readings": [ {} ] } } ```
--- ### `updateUseCase` Update an existing use case configuration `PUT /v1/integrations/{integrationId}/use-cases/{useCaseId}` ```ts const { data } = await client.updateUseCase( { integrationId: 'example', useCaseId: 'example', }, { name: 'string', slug: 'string', enabled: true, change_description: 'string', type: 'inbound', configuration: { direct: true, interactive: 'on_request', entities: [ { /* ... */ } ], meter_readings: [ { /* ... */ } ] } }, ) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": { "direct": true, "interactive": "on_request", "entities": [ {} ], "meter_readings": [ {} ] } } ```
--- ### `deleteUseCase` Delete a use case from an integration `DELETE /v1/integrations/{integrationId}/use-cases/{useCaseId}` ```ts const { data } = await client.deleteUseCase({ integrationId: 'example', useCaseId: 'example', }) ```
Response ```json { "message": "string" } ```
--- ### `listUseCaseHistory` Retrieve historical versions of a use case's configuration. History entries are returned in reverse chronological order (newest first). Use the 'cursor' parameter for pagination to fetch additional en `GET /v1/integrations/{integrationId}/use-cases/{useCaseId}/history` ```ts const { data } = await client.listUseCaseHistory({ integrationId: 'example', useCaseId: 'example', cursor: 'example', }) ```
Response ```json { "history": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "useCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "history_created_at": "1970-01-01T00:00:00.000Z", "type": "inbound", "configuration": {} } ], "next_cursor": "string" } ```
--- ### `listDocumentationPages` Retrieve all documentation pages of an integration, without their markdown content. An integration has at most one general page plus at most one page per use case. The page id is 'general' for the int `GET /v1/integrations/{integrationId}/documentation` ```ts const { data } = await client.listDocumentationPages({ integrationId: 'example', }) ```
Response ```json { "pages": [ { "id": "general", "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "scope": "integration", "use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "title": "string", "created_at": "1970-01-01T00:00:00.000Z", "created_by": "string", "updated_at": "1970-01-01T00:00:00.000Z", "updated_by": "string" } ] } ```
--- ### `getDocumentationPage` Retrieve a single documentation page including its markdown content `GET /v1/integrations/{integrationId}/documentation/{docId}` ```ts const { data } = await client.getDocumentationPage({ integrationId: 'example', docId: 'example', }) ```
Response ```json { "id": "general", "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "scope": "integration", "use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "title": "string", "created_at": "1970-01-01T00:00:00.000Z", "created_by": "string", "updated_at": "1970-01-01T00:00:00.000Z", "updated_by": "string", "content": "string" } ```
--- ### `upsertDocumentationPage` Create or update the documentation page identified by docId. Upsert semantics enforce the invariant of one general page per integration and one page per use case. For use case pages the use case must `PUT /v1/integrations/{integrationId}/documentation/{docId}` ```ts const { data } = await client.upsertDocumentationPage( { integrationId: 'example', docId: 'example', }, { title: 'string', content: 'string' }, ) ```
Response ```json { "id": "general", "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "scope": "integration", "use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "title": "string", "created_at": "1970-01-01T00:00:00.000Z", "created_by": "string", "updated_at": "1970-01-01T00:00:00.000Z", "updated_by": "string", "content": "string" } ```
--- ### `deleteDocumentationPage` Delete a documentation page `DELETE /v1/integrations/{integrationId}/documentation/{docId}` ```ts const { data } = await client.deleteDocumentationPage({ integrationId: 'example', docId: 'example', }) ```
Response ```json { "message": "string" } ```
--- ### `listIntegrationsV2` Retrieve all integrations with embedded use cases for the authenticated organization `GET /v2/integrations` ```ts const { data } = await client.listIntegrationsV2() ```
Response ```json { "integrations": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [], "maps": [], "settings": {}, "integration_type": "erp", "connector_config": {}, "protected": true, "_manifest": ["string"], "use_cases": [] } ] } ```
--- ### `createIntegrationV2` Create a new integration with embedded use cases. `POST /v2/integrations` ```ts const { data } = await client.createIntegrationV2( null, { name: 'string', description: 'string', access_token_ids: ['string'], app_ids: ['string'], environment_config: [ { key: 'string', label: 'string', type: 'String', description: 'string', required: false, order: 0 } ], maps: [ { key: 'string', label: 'string', description: 'string', value: {} } ], settings: { autoRefresh: { enabled: false, freshnessThresholdMinutes: 1 }, notifications: { enabled: true, recipients: [ /* ... */ ], defaultChannels: { /* ... */ }, monitoredUseCases: ['string'], monitoredCodes: ['string'], rules: [ /* ... */ ], digest: { /* ... */ }, muteUntil: '1970-01-01T00:00:00.000Z' } }, integration_type: 'erp', connector_config: { base_url: 'string', auth: { type: 'oauth2_client_credentials', token_url: 'string', client_id: 'string', client_secret: 'string', scope: 'string', audience: 'string', resource: 'string', body_params: {}, headers: {}, query_params: {}, api_key_header: 'string', api_key: 'string', token: 'string' }, types_versions: [ { /* ... */ } ], latest_types_version: 'string', latest_types_package_name: 'string' }, protected: true, _manifest: ['string'], use_cases: [ { id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', name: 'string', slug: 'string', enabled: true, change_description: 'string', type: 'inbound', configuration: { /* ... */ } } ] }, ) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [ { "key": "string", "label": "string", "type": "String", "description": "string", "required": false, "order": 0 } ], "maps": [ { "key": "string", "label": "string", "description": "string", "value": {} } ], "settings": { "autoRefresh": { "enabled": false, "freshnessThresholdMinutes": 1 }, "notifications": { "enabled": true, "recipients": [], "defaultChannels": {}, "monitoredUseCases": ["string"], "monitoredCodes": ["string"], "rules": [], "digest": {}, "muteUntil": "1970-01-01T00:00:00.000Z" } }, "integration_type": "erp", "connector_config": { "base_url": "string", "auth": { "type": "oauth2_client_credentials", "token_url": "string", "client_id": "string", "client_secret": "string", "scope": "string", "audience": "string", "resource": "string", "body_params": {}, "headers": {}, "query_params": {}, "api_key_header": "string", "api_key": "string", "token": "string" }, "types_versions": [ {} ], "latest_types_version": "string", "latest_types_package_name": "string" }, "protected": true, "_manifest": ["string"], "use_cases": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": {} } ] } ```
--- ### `getIntegrationV2` Retrieve a specific integration with all its embedded use cases `GET /v2/integrations/{integrationId}` ```ts const { data } = await client.getIntegrationV2({ integrationId: 'example', }) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [ { "key": "string", "label": "string", "type": "String", "description": "string", "required": false, "order": 0 } ], "maps": [ { "key": "string", "label": "string", "description": "string", "value": {} } ], "settings": { "autoRefresh": { "enabled": false, "freshnessThresholdMinutes": 1 }, "notifications": { "enabled": true, "recipients": [], "defaultChannels": {}, "monitoredUseCases": ["string"], "monitoredCodes": ["string"], "rules": [], "digest": {}, "muteUntil": "1970-01-01T00:00:00.000Z" } }, "integration_type": "erp", "connector_config": { "base_url": "string", "auth": { "type": "oauth2_client_credentials", "token_url": "string", "client_id": "string", "client_secret": "string", "scope": "string", "audience": "string", "resource": "string", "body_params": {}, "headers": {}, "query_params": {}, "api_key_header": "string", "api_key": "string", "token": "string" }, "types_versions": [ {} ], "latest_types_version": "string", "latest_types_package_name": "string" }, "protected": true, "_manifest": ["string"], "use_cases": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": {} } ] } ```
--- ### `updateIntegrationV2` Update an existing integration with embedded use cases. The integration must already exist. Use cases are updated declaratively: - Use cases in the request with matching IDs are updated - Use cases in `PUT /v2/integrations/{integrationId}` ```ts const { data } = await client.updateIntegrationV2( { integrationId: 'example', }, { name: 'string', description: 'string', access_token_ids: ['string'], app_ids: ['string'], environment_config: [ { key: 'string', label: 'string', type: 'String', description: 'string', required: false, order: 0 } ], maps: [ { key: 'string', label: 'string', description: 'string', value: {} } ], settings: { autoRefresh: { enabled: false, freshnessThresholdMinutes: 1 }, notifications: { enabled: true, recipients: [ /* ... */ ], defaultChannels: { /* ... */ }, monitoredUseCases: ['string'], monitoredCodes: ['string'], rules: [ /* ... */ ], digest: { /* ... */ }, muteUntil: '1970-01-01T00:00:00.000Z' } }, integration_type: 'erp', connector_config: { base_url: 'string', auth: { type: 'oauth2_client_credentials', token_url: 'string', client_id: 'string', client_secret: 'string', scope: 'string', audience: 'string', resource: 'string', body_params: {}, headers: {}, query_params: {}, api_key_header: 'string', api_key: 'string', token: 'string' }, types_versions: [ { /* ... */ } ], latest_types_version: 'string', latest_types_package_name: 'string' }, protected: true, _manifest: ['string'], use_cases: [ { id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', name: 'string', slug: 'string', enabled: true, change_description: 'string', type: 'inbound', configuration: { /* ... */ } } ] }, ) ```
Response ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "orgId": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "name": "string", "description": "string", "access_token_ids": ["string"], "app_ids": ["string"], "environment_config": [ { "key": "string", "label": "string", "type": "String", "description": "string", "required": false, "order": 0 } ], "maps": [ { "key": "string", "label": "string", "description": "string", "value": {} } ], "settings": { "autoRefresh": { "enabled": false, "freshnessThresholdMinutes": 1 }, "notifications": { "enabled": true, "recipients": [], "defaultChannels": {}, "monitoredUseCases": ["string"], "monitoredCodes": ["string"], "rules": [], "digest": {}, "muteUntil": "1970-01-01T00:00:00.000Z" } }, "integration_type": "erp", "connector_config": { "base_url": "string", "auth": { "type": "oauth2_client_credentials", "token_url": "string", "client_id": "string", "client_secret": "string", "scope": "string", "audience": "string", "resource": "string", "body_params": {}, "headers": {}, "query_params": {}, "api_key_header": "string", "api_key": "string", "token": "string" }, "types_versions": [ {} ], "latest_types_version": "string", "latest_types_package_name": "string" }, "protected": true, "_manifest": ["string"], "use_cases": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "type": "inbound", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "configuration": {} } ] } ```
--- ### `deleteIntegrationV2` Delete an integration and all its use cases `DELETE /v2/integrations/{integrationId}` ```ts const { data } = await client.deleteIntegrationV2({ integrationId: 'example', }) ```
Response ```json { "message": "string" } ```
--- ### `listNotificationHistory` Returns the cursor-paginated, newest-first notification history for an integration (every real notification decision — both fired and suppressed). Requires the `integration:view` permission on the int `GET /v2/integrations/{integrationId}/notifications/history` ```ts const { data } = await client.listNotificationHistory({ integrationId: 'example', cursor: 'example', limit: 1, type: 'example', }) ```
Response ```json { "history": [ { "id": "string", "type": "string", "state_transition": "string", "severity": "error", "title": "string", "occurred_at": "1970-01-01T00:00:00.000Z", "notified": true, "suppressed_reason": "muted", "recipients": ["string"], "context": {}, "created_at": "1970-01-01T00:00:00.000Z" } ], "next_cursor": "string" } ```
--- ### `testSendNotification` Renders and sends ONE representative notification of the requested kind/type to the CALLING USER ONLY (never any other recipient), so an operator can preview how a notification looks. A test send does `POST /v2/integrations/{integrationId}/notifications/test` ```ts const { data } = await client.testSendNotification( { integrationId: 'example', }, { kind: 'alert', type: 'string', channels: ['email'] }, ) ``` --- ### `getNotificationStatus` Returns the live per-rule alert state and (for 'auto' rules) the current hour-of-week baseline band for an integration's notification monitoring. Reflects the latest 5-minute sweep — near-real-time, n `GET /v2/integrations/{integrationId}/notifications/status` ```ts const { data } = await client.getNotificationStatus({ integrationId: 'example', include: 'example', }) ```
Response ```json { "health": "healthy", "evaluated_at": "1970-01-01T00:00:00.000Z", "rules": [ { "rule_id": "string", "state": "ok", "last_fired_at": "1970-01-01T00:00:00.000Z", "last_cleared_at": "1970-01-01T00:00:00.000Z", "last_evaluation": { "evaluated_at": "1970-01-01T00:00:00.000Z", "observed": 0, "threshold": 0, "suppressed_reason": "sample_size" }, "baseline": { "is_mature": true, "computed_at": "1970-01-01T00:00:00.000Z", "median": 0, "mad": 0, "upper": 0, "buckets": [ { "dow": 1, "hour": 0, "median": 0, "mad": 0 } ] } } ] } ```
--- ### `getSecureProxyWhitelist` Returns the current allowed_domains, allowed_ips, and vpc_mode for a secure_proxy use case. Staff-only — gated by internal-auth issuer AND admin-portal Cognito user pool membership. Rejects Login-As t `GET /v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist` ```ts const { data } = await client.getSecureProxyWhitelist({ integrationId: 'example', useCaseId: 'example', }) ```
Response ```json { "vpc_mode": "static_ip", "allowed_domains": ["string"], "allowed_ips": ["string"] } ```
--- ### `updateSecureProxyWhitelist` Replaces allowed_domains and/or allowed_ips on a secure_proxy use case. At least one of the two fields is required. Validation mirrors the CLI's `validateDomainPatterns` / `validateCidrs`. Writes a US `PUT /v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist` ```ts const { data } = await client.updateSecureProxyWhitelist( { integrationId: 'example', useCaseId: 'example', }, { allowed_domains: ['string'], allowed_ips: ['string'] }, ) ```
Response ```json { "vpc_mode": "static_ip", "allowed_domains": ["string"], "allowed_ips": ["string"] } ```
--- ### `listSecureProxyWhitelistHistory` Returns the most recent USECASE_HISTORY entries for a secure_proxy use case, in reverse chronological order (newest first). Each entry includes the actor email (`changed_by`), the ISO-8601 timestamp ( `GET /v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist/history` ```ts const { data } = await client.listSecureProxyWhitelistHistory({ integrationId: 'example', useCaseId: 'example', limit: 1, }) ```
Response ```json { "history": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "useCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "enabled": true, "change_description": "string", "changed_by": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z", "history_created_at": "1970-01-01T00:00:00.000Z", "type": "secure_proxy", "configuration": { "vpc_mode": "static_ip", "allowed_domains": ["string"], "allowed_ips": ["string"] } } ] } ```
--- ### `setIntegrationAppMapping` Creates or updates a mapping from an app/component to an integration. This allows ERP updates sent via app_id and component_id to be associated with a specific integration configuration. `PUT /v1/integrations/{integrationId}/app-mapping` ```ts const { data } = await client.setIntegrationAppMapping( { integrationId: 'example', }, { app_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', component_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', overwrite: false }, ) ```
Response ```json { "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ```
--- ### `deleteIntegrationAppMapping` Removes a mapping from an app/component to an integration. `DELETE /v1/integrations/{integrationId}/app-mapping` ```ts const { data } = await client.deleteIntegrationAppMapping( { integrationId: 'example', }, { app_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', component_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6' }, ) ```
Response ```json { "message": "string" } ```
--- ### `getOutboundStatus` Get the status of all outbound use cases for a specific integration. Returns conflict information when events or webhooks are disabled but the use case is enabled. `GET /v1/integrations/{integrationId}/outbound-status` ```ts const { data } = await client.getOutboundStatus({ integrationId: 'example', }) ```
Response ```json { "useCases": [ { "useCaseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "useCaseEnabled": true, "eventCatalogEvent": "contract.created", "eventEnabled": true, "webhooks": [ { "webhookId": "string", "webhookName": "string", "enabled": true } ], "status": "ok", "conflicts": [ { "type": "event_disabled", "webhookId": "string", "message": "string" } ], "poll": { "queue_depth": 0, "oldest_unconsumed_age_seconds": 0, "last_poll_at": "1970-01-01T00:00:00.000Z", "last_ack_at": "1970-01-01T00:00:00.000Z", "blocked": true, "dlq_count": 0 }, "file_proxy": [ { "mapping_id": "string", "use_case_slug": "string", "resolved": true, "target_use_case_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "target_enabled": true, "target_updated_at": "1970-01-01T00:00:00.000Z", "unresolved_reason": "not_found" } ] } ] } ```
--- ### `getEntitySyncStatus` Get the inbound ERP sync status of an entity: when each integration last synchronized (checked) the entity against the ERP, and when it last actually changed it. `last_synced_at` also advances on no-o `GET /v1/integrations/entities/{entityId}/sync-status` ```ts const { data } = await client.getEntitySyncStatus({ entityId: 'example', integration_id: 'example', }) ```
Response ```json { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sync_states": [ { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity_slug": "contract", "use_case_id": "string", "last_synced_at": "1970-01-01T00:00:00.000Z", "last_changed_at": "1970-01-01T00:00:00.000Z", "last_operation": "create", "last_event_id": "string", "readings_last_synced_at": "1970-01-01T00:00:00.000Z", "readings_last_operation": "upsert", "readings_last_event_id": "string" } ] } ```
--- ### `pollOutboundMessages` Poll outbound messages for an integration's poll-mode use cases. Takes a lease on the head-of-line batch of the integration's FIFO stream: the returned messages stay invisible to subsequent polls unti `POST /v1/integrations/{integrationId}/outbound/messages/poll` ```ts const { data } = await client.pollOutboundMessages( { integrationId: 'example', }, { limit: 10 }, ) ```
Response ```json { "messages": [ { "id": "string", "lease_token": "string", "use_case_id": "string", "event_name": "string", "event_id": "string", "group": "string", "org_id": "string", "payload": {}, "mapping_version": "3f2a9c1b7d4e8f60", "enqueued_at": "1970-01-01T00:00:00.000Z" } ], "visibility_timeout_seconds": 0, "has_more": true } ```
--- ### `ackOutboundMessages` Acknowledge polled outbound messages. Acks are validated against the active lease and committed as a prefix-contiguous cursor advance: messages must be acknowledged in stream order. Out-of-order acks `POST /v1/integrations/{integrationId}/outbound/messages/ack` ```ts const { data } = await client.ackOutboundMessages( { integrationId: 'example', }, { acks: [ { id: 'string', lease_token: 'string' } ] }, ) ```
Response ```json { "results": [ { "id": "string", "status": "accepted", "reason": "stale_lease" } ] } ```
--- ### `listOutboundDlqMessages` List an integration's dead-lettered outbound queue messages (poison_policy enforcement and operator skips move messages here). Operator endpoint — requires the `integration:manage` grant. Message payl `GET /v1/integrations/{integrationId}/outbound/messages/dlq` ```ts const { data } = await client.listOutboundDlqMessages({ integrationId: 'example', limit: 1, next_token: 'example', }) ```
Response ```json { "items": [ { "id": "string", "use_case_id": "string", "event_name": "string", "event_id": "string", "enqueued_at": "1970-01-01T00:00:00.000Z", "dead_lettered_at": "1970-01-01T00:00:00.000Z", "delivery_attempts": 0, "reason": "string", "mapping_error": "string", "mapping_version": "string", "expires_at": "1970-01-01T00:00:00.000Z" } ], "next_token": "string" } ```
--- ### `redriveOutboundDlqMessages` Redrive selected dead-lettered messages back into the live stream. Operator endpoint — requires the `integration:manage` grant. A redriven message is re-enqueued at the tail with a new id and sequence `POST /v1/integrations/{integrationId}/outbound/messages/dlq/redrive` ```ts const { data } = await client.redriveOutboundDlqMessages( { integrationId: 'example', }, { ids: ['string'], reapply_mapping: false }, ) ```
Response ```json { "results": [ { "id": "string", "status": "redriven", "mapping_error": "string" } ] } ```
--- ### `unblockOutboundStream` Unblock an integration's outbound stream halted by the `block` poison policy: skips (dead-letters) the current blocked head message, emitting MSG_DEAD_LETTERED and letting the next message become the `POST /v1/integrations/{integrationId}/outbound/messages/unblock` ```ts const { data } = await client.unblockOutboundStream( { integrationId: 'example', }, { reason: 'string' }, ) ```
Response ```json { "unblocked": true, "dead_lettered_id": "string" } ```
--- ### `simulateOutboundMapping` Preview a poll delivery's `jsonata_expression` without saving or enqueueing anything. The expression is checked and evaluated exactly as at enqueue time: the same length, syntax and binding checks, th `POST /v1/integrations/{integrationId}/outbound/mapping-simulation` ```ts const { data } = await client.simulateOutboundMapping( { integrationId: 'example', }, { jsonata_expression: '{ "contract_number": contract.contract_number, "status": $mapValue($env.erp.statuses, contract.status) }', payload: {}, event_id: 'string', event_catalog_event: 'contract.updated' }, ) ```
Response ```json { "valid": true, "output": {}, "error": { "code": "syntax_error", "message": "string", "position": 0 }, "mapping_version": "3f2a9c1b7d4e8f60", "input": {} } ```
--- ### `queryAccessLogs` Query API access logs for a specific integration's organization. Returns access token usage analytics filtered by user_id (access token). Supports infinite scroll pagination with cursor-based navigati `POST /v1/integrations/{integrationId}/monitoring/access-logs` ```ts const { data } = await client.queryAccessLogs( { integrationId: 'example', }, { token_id: 'api_5ZugdRXasLfWBypHi93Fk', service: 'entity', method: 'GET', path: '/v1/entity', status: 200, from_date: '2025-01-01T00:00:00Z', to_date: '2025-01-31T23:59:59Z', limit: 50, cursor: { timestamp: '1970-01-01T00:00:00.000Z', request_id: 'string' } }, ) ```
Response ```json { "data": [ { "timestamp": "1970-01-01T00:00:00.000Z", "environment": "string", "service": "string", "request_id": "string", "method": "string", "path": "string", "status": 0, "response_latency_ms": 0, "response_length": 0, "token_id": "string", "org_id": "string", "origin": "string", "source_ip": "string" } ], "next_cursor": { "timestamp": "1970-01-01T00:00:00.000Z", "request_id": "string" }, "has_more": true } ```
--- ### `queryMonitoringEventsV2` Query monitoring events from the unified erp_monitoring_v2 table. Returns all event types (inbound, outbound, file_proxy, etc.) in a single list. Replaces the separate v1 inbound-events and outbound-e `POST /v2/integrations/{integrationId}/monitoring/events` ```ts const { data } = await client.queryMonitoringEventsV2( { integrationId: 'example', }, { use_case_id: 'string', use_case_type: 'inbound', level: 'success', code: 'string', event_id: 'string', correlation_id: 'string', from_date: '2025-01-01T00:00:00Z', to_date: '2025-01-31T23:59:59Z', limit: 50, cursor: { created_at: '1970-01-01T00:00:00.000Z', id: '3fa85f64-5717-4562-b3fc-2c963f66afa6' } }, ) ```
Response ```json { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "org_id": "string", "integration_id": "string", "event_id": "string", "correlation_id": "string", "use_case_id": "string", "use_case_type": "inbound", "level": "success", "code": "ACK_CONFIRMED", "message": "string", "detail": {}, "created_at": "1970-01-01T00:00:00.000Z" } ], "next_cursor": { "created_at": "1970-01-01T00:00:00.000Z", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "has_more": true } ```
--- ### `getMonitoringStatsV2` Get aggregated statistics from the unified erp_monitoring_v2 table. Returns combined metrics for all event types with optional breakdowns. `POST /v2/integrations/{integrationId}/monitoring/stats` ```ts const { data } = await client.getMonitoringStatsV2( { integrationId: 'example', }, { from_date: '2025-01-01T00:00:00Z', to_date: '2025-01-31T23:59:59Z', correlation_id: 'imp_01M3799K98B6TG7GV7Q2DQT554', correlation_ids: ['imp_01M3799K98B6TG7GV7Q2DQT554', 'imp_01M374YPQ0E7ZB0VYJZSK72M4E'], use_case_type: 'inbound', use_case_types: ['inbound'], group_by: 'use_case_id', source: 'monitoring' }, ) ```
Response ```json { "total_events": 0, "success_count": 0, "error_count": 0, "warning_count": 0, "skipped_count": 0, "info_count": 0, "ack_timeout_count": 0, "success_rate": 0, "last_error_at": "1970-01-01T00:00:00.000Z", "last_event_at": "1970-01-01T00:00:00.000Z", "breakdown": [ {} ] } ```
--- ### `getMonitoringTimeSeriesV2` Get time-series aggregated event counts from the unified erp_monitoring_v2 table. Returns bucketed counts for chart rendering. `POST /v2/integrations/{integrationId}/monitoring/time-series` ```ts const { data } = await client.getMonitoringTimeSeriesV2( { integrationId: 'example', }, { from_date: '2025-01-01T00:00:00Z', to_date: '2025-01-31T23:59:59Z', interval: '5m', use_case_type: 'inbound', group_by: 'use_case_type' }, ) ```
Response ```json { "interval": "5m", "from_date": "1970-01-01T00:00:00.000Z", "to_date": "1970-01-01T00:00:00.000Z", "buckets": [ { "timestamp": "1970-01-01T00:00:00.000Z", "success_count": 0, "error_count": 0, "warning_count": 0, "skipped_count": 0, "info_count": 0, "total_count": 0, "breakdown": [ { "use_case_type": "inbound", "use_case_id": "string", "success_count": 0, "error_count": 0, "warning_count": 0, "skipped_count": 0, "info_count": 0, "total_count": 0 } ] } ] } ```
--- ### `getAssociatedMonitoringEvents` Returns all monitoring events sharing the same event_id, ordered chronologically. Also includes the original inbound event payload from erp_incoming_events if available. Used to display a full event t `GET /v2/integrations/{integrationId}/monitoring/events/{eventId}/associated` ```ts const { data } = await client.getAssociatedMonitoringEvents({ integrationId: 'example', eventId: 'example', }) ```
Response ```json { "monitoring_events": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "org_id": "string", "integration_id": "string", "event_id": "string", "correlation_id": "string", "use_case_id": "string", "use_case_type": "inbound", "level": "success", "code": "ACK_CONFIRMED", "message": "string", "detail": {}, "created_at": "1970-01-01T00:00:00.000Z" } ], "inbound_event": {} } ```
--- ### `ingestExternalMonitoringEvents` Ingest monitoring spans produced by an EXTERNAL system (e.g. an integration middleware), so the Integration Hub is the central monitoring point and the cross-system event trace spans both the external `POST /v2/integrations/{integrationId}/monitoring/external-events` ```ts const { data } = await client.ingestExternalMonitoringEvents( { integrationId: 'example', }, { events: [ { correlation_id: 'string', level: 'string', use_case_slug: 'string', occurred_at: '1970-01-01T00:00:00.000Z', message: 'string', detail: {} } ] }, ) ``` --- ### `getMonitoringTraceByCorrelation` Returns the cross-system event trace for a `correlation_id`: every monitoring span sharing it — external spans (middleware) plus epilot's own processing spans — ordered chronologically, with a rolled- `GET /v2/integrations/{integrationId}/monitoring/traces/{correlationId}` ```ts const { data } = await client.getMonitoringTraceByCorrelation({ integrationId: 'example', correlationId: 'example', }) ```
Response ```json { "correlation_id": "string", "status": "success", "started_at": "1970-01-01T00:00:00.000Z", "ended_at": "1970-01-01T00:00:00.000Z", "span_count": 0, "truncated": true, "spans": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "org_id": "string", "integration_id": "string", "event_id": "string", "correlation_id": "string", "use_case_id": "string", "use_case_type": "inbound", "level": "success", "code": "ACK_CONFIRMED", "message": "string", "detail": {}, "created_at": "1970-01-01T00:00:00.000Z" } ], "inbound_event": {} } ```
--- ### `getMonitoringRunCompletionV2` Per-event completion of one or more runs (every monitoring event sharing a `correlation_id`), each reduced to "how many events have reached a final outcome, and how many are still going". Unlike `getM `POST /v2/integrations/{integrationId}/monitoring/runs/completion` ```ts const { data } = await client.getMonitoringRunCompletionV2( { integrationId: 'example', }, { correlation_ids: ['string'] }, ) ```
Response ```json { "runs": [ { "correlation_id": "string", "seen": 0, "in_flight": 0, "retrying": 0, "success": 0, "warning": 0, "error": 0, "info": 0, "entries": { "total": 0, "error": 0, "warning": 0, "success": 0, "info": 0, "retry": 0 }, "last_activity_at": "1970-01-01T00:00:00.000Z" } ] } ```
--- ### `listSecureProxies` Lists all secure_proxy use cases across all integrations for the authenticated organization. Returns minimal data suitable for dropdowns and selection UIs. `GET /v1/integrations/secure-proxies` ```ts const { data } = await client.listSecureProxies() ```
Response ```json { "secure_proxies": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "slug": "string", "enabled": true, "vpc_mode": "static_ip", "allowed_domains": ["string"], "allowed_ips": ["string"], "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "integration_name": "string" } ] } ```
--- ### `secureProxy` Routes an HTTP request through a VPC with either static IP egress or VPN secure link access. The VPC mode is determined by the referenced secure_proxy use case configuration. For secure_link mode, the `POST /v1/secure-proxy` ```ts const { data } = await client.secureProxy( null, { integration_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', use_case_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', use_case_slug: 'string', url: 'https://example.com/path', method: 'GET', headers: {}, body: {}, response_type: 'json' }, ) ```
Response ```json { "status_code": 0, "headers": {}, "body": {} } ```
--- ### `managedCallExecute` Execute a managed call operation synchronously. The slug in the path acts as the RPC method name. Calls an external partner API with JSONata mapping on both request and response. `POST /v1/managed-call/{slug}/execute` ```ts const { data } = await client.managedCallExecute( { slug: 'example', }, { integration_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6', payload: {}, correlation_id: 'string' }, ) ```
Response ```json {} ```
--- ### `generateTypesPreview` 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 l `POST /v1/integrations/{integrationId}/generate-types-preview` ```ts const { data } = await client.generateTypesPreview({ integrationId: 'example', }) ``` --- ### `generateTypes` 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 `POST /v1/integrations/{integrationId}/generate-types` ```ts const { data } = await client.generateTypes( { integrationId: 'example', }, { package_name: '@epilot/hems-cleverpv', version: '1.0.0', description: 'string', domain_package: '@epilot/hems', domain_map_name: 'HemsUseCaseMap', annotations: {} }, ) ```
Response ```json { "package_name": "string", "version": "string", "files": {}, "warnings": ["string"] } ```
--- ### `commitTypes` 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. `POST /v1/integrations/{integrationId}/commit-types` ```ts const { data } = await client.commitTypes( { integrationId: 'example', }, { package_name: '@epilot/hems-cleverpv', version: '1.0.0', annotations: {} }, ) ```
Response ```json { "committed": true, "warnings": ["string"] } ```
--- ### `createErpImport` Register an already-uploaded file (S3 ref) as a pricing-file import job. Returns the job and a file preview. Nothing runs yet: no use case is chosen and no validation starts here. Optionally rank cand `POST /v2/erp/imports` ```ts const { data } = await client.createErpImport( null, { s3_reference: { bucket: 'string', key: 'string' }, include_preview: false, import_id: 'string' }, ) ```
Response ```json { "job": { "import_id": "string", "org_id": "string", "created_by": "string", "integration_id": "string", "use_case_slug": "string", "format": "csv", "status": "PENDING", "s3_input_ref": { "bucket": "string", "key": "string" }, "size_bytes": 0, "column_count": 0, "validation": { "total_rows": 0, "blocking": 0, "warnings": 0, "entities": {}, "entity_details": [ { "mapping_index": 0, "entity_schema": "string", "business_key": {}, "variants": 0, "versions": 0, "condition_attributes": ["grid_area"], "version_attribute": "valid_from" } ], "issues": [ { "code": "UNIQUE_ID_COLUMN_MISSING", "severity": "warning", "columns": [ { "name": "string", "entity": "string" } ], "attributes": [ { "name": "string", "entity": "string" } ], "lines": [0], "subject": "string", "row": 0, "expected": "number" } ] }, "progress": { "processed_rows": 0, "total_rows": 0, "events_published": 0 }, "error": { "code": "VALIDATION_BLOCKED", "message": "string" }, "correlation_id": "string", "activity_id": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z" }, "preview": { "columns": ["string"], "rows": [ ["string"] ] } } ```
--- ### `listErpImports` List recent pricing-file import jobs for the org, newest first. `GET /v2/erp/imports` ```ts const { data } = await client.listErpImports({ limit: 1, cursor: 'example', }) ```
Response ```json { "results": [ { "import_id": "string", "org_id": "string", "created_by": "string", "integration_id": "string", "use_case_slug": "string", "format": "csv", "status": "PENDING", "s3_input_ref": { "bucket": "string", "key": "string" }, "size_bytes": 0, "column_count": 0, "validation": { "total_rows": 0, "blocking": 0, "warnings": 0, "entities": {}, "entity_details": [ { "mapping_index": 0, "entity_schema": "string", "business_key": {}, "variants": 0, "versions": 0, "condition_attributes": ["grid_area"], "version_attribute": "valid_from" } ], "issues": [ { "code": "UNIQUE_ID_COLUMN_MISSING", "severity": "warning", "columns": [ { "name": "string", "entity": "string" } ], "attributes": [ { "name": "string", "entity": "string" } ], "lines": [0], "subject": "string", "row": 0, "expected": "number" } ] }, "progress": { "processed_rows": 0, "total_rows": 0, "events_published": 0 }, "error": { "code": "VALIDATION_BLOCKED", "message": "string" }, "correlation_id": "string", "activity_id": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z" } ], "next_cursor": "string" } ```
--- ### `getErpImport` Get a pricing-file import job (status, counts, result links). `GET /v2/erp/imports/{importId}` ```ts const { data } = await client.getErpImport({ importId: 'example', }) ```
Response ```json { "import_id": "string", "org_id": "string", "created_by": "string", "integration_id": "string", "use_case_slug": "string", "format": "csv", "status": "PENDING", "s3_input_ref": { "bucket": "string", "key": "string" }, "size_bytes": 0, "column_count": 0, "validation": { "total_rows": 0, "blocking": 0, "warnings": 0, "entities": {}, "entity_details": [ { "mapping_index": 0, "entity_schema": "string", "business_key": {}, "variants": 0, "versions": 0, "condition_attributes": ["grid_area"], "version_attribute": "valid_from" } ], "issues": [ { "code": "UNIQUE_ID_COLUMN_MISSING", "severity": "warning", "columns": [ { "name": "string", "entity": "string" } ], "attributes": [ { "name": "string", "entity": "string" } ], "lines": [0], "subject": "string", "row": 0, "expected": "number" } ] }, "progress": { "processed_rows": 0, "total_rows": 0, "events_published": 0 }, "error": { "code": "VALIDATION_BLOCKED", "message": "string" }, "correlation_id": "string", "activity_id": "string", "created_at": "1970-01-01T00:00:00.000Z", "updated_at": "1970-01-01T00:00:00.000Z" } ```
--- ### `deleteErpImport` Remove an import and the file it owns. Allowed from any status: an import whose run is still in flight is stopped by the deletion, and rows it already wrote stay written. `DELETE /v2/erp/imports/{importId}` ```ts const { data } = await client.deleteErpImport({ importId: 'example', }) ``` --- ### `getErpImportPreview` The file preview of an existing import: its columns and first data rows, the same sample `createErpImport` returns with `include_preview`. Lets a client that opens a job later show its file, and is in `GET /v2/erp/imports/{importId}/preview` ```ts const { data } = await client.getErpImportPreview({ importId: 'example', }) ```
Response ```json { "columns": ["string"], "rows": [ ["string"] ] } ```
--- ### `downloadErpImportFile` A short-lived presigned URL that downloads the file this import was registered with — the import's own copy, so exactly what `:validate` and `:execute` read. The URL serves the file as an attachment u `GET /v2/erp/imports/{importId}/download` ```ts const { data } = await client.downloadErpImportFile({ importId: 'example', }) ```
Response ```json { "download_url": "https://example.com/path", "filename": "string", "expires_at": "1970-01-01T00:00:00.000Z" } ```
--- ### `validateErpImport` Choose the use case to read this file with, and start the validate phase. Callable from PENDING, READY and FAILED — so a wrong choice is corrected by calling this again with a different use case, rath `POST /v2/erp/imports/{importId}:validate` ```ts const { data } = await client.validateErpImport( { importId: 'example', }, { integration_id: 'string', use_case_slug: 'string' }, ) ``` --- ### `suggestErpImportUseCases` Rank the org's inbound use cases against this file's columns — the input to the ranked picker ("matches 6 of your 7 columns"). Optional: skip this and call `:validate` directly when the use case is al `POST /v2/erp/imports/{importId}:suggest-use-cases` ```ts const { data } = await client.suggestErpImportUseCases({ importId: 'example', }) ```
Response ```json { "file_columns": 0, "suggestions": [ { "integration_id": "string", "integration_name": "string", "use_case_slug": "string", "use_case_name": "string", "entity_types": 0, "matched_columns": 0 } ] } ```
--- ### `executeErpImport` Confirm and run the write phase of a validated import. Only a READY job may be executed; any other status returns 409. The verdict is re-checked against live inputs first: if the mapping or an entity `POST /v2/erp/imports/{importId}:execute` ```ts const { data } = await client.executeErpImport( { importId: 'example', }, { ack_warnings: true }, ) ``` --- ### `abortErpImport` Ask a running import to stop. Valid while the job is VALIDATING or PROCESSING; any other status returns 409. The stop is cooperative: the job passes through CANCELLING and typically reaches CANCELLED `POST /v2/erp/imports/{importId}:abort` ```ts const { data } = await client.abortErpImport({ importId: 'example', }) ``` --- ## Schemas ### `S3Reference` ```ts type S3Reference = { bucket: string key: string } ``` ### `CreateErpImportRequest` Register an already-uploaded file as an import. The use case is chosen later, via `:validate` — upload and interpretation are separate decisions. ```ts type CreateErpImportRequest = { s3_reference: { bucket: string key: string } include_preview?: boolean import_id?: string } ``` ### `ValidateErpImportRequest` ```ts type ValidateErpImportRequest = { integration_id: string use_case_slug: string } ``` ### `ErpImportUseCaseSuggestion` ```ts type ErpImportUseCaseSuggestion = { integration_id: string integration_name: string use_case_slug: string use_case_name: string entity_types: number matched_columns: number } ``` ### `SuggestErpImportUseCasesResponse` ```ts type SuggestErpImportUseCasesResponse = { file_columns: number suggestions: Array<{ integration_id: string integration_name: string use_case_slug: string use_case_name: string entity_types: number matched_columns: number }> } ``` ### `ExecuteErpImportRequest` Confirmation options. Required only when the verdict carries warnings — a clean import needs no body at all. ```ts type ExecuteErpImportRequest = { ack_warnings?: boolean } ``` ### `ErpImportIssue` A problem found during validation, scoped to the file as a whole rather than to individual rows. `code` is the translation key and the other fields are its parameters — there is deliberately no message to display. Each code appears at most once (once per `expected` for `VALUE_FORMAT_INVALID`), with ```ts type ErpImportIssue = { code: "UNIQUE_ID_COLUMN_MISSING" | "MAPPED_COLUMN_MISSING" | "MALFORMED_ROW" | "INVALID_ENCODING" | "EMPTY_FILE" | "TOO_MANY_ROWS" | "BLANK_ROWS_SKIPPED" | "TIER_ROWS_NOT_GROUPED" | "TIER_BANDS_CONFLICT" | "CONDITION_VALUE_MISSING" | "VARIANT_VALUE_CONFLICT" | "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_NOT_IN_SCHEMA" | "IS_CONDITIONAL_NOT_CONSTANT" | "SCHEMA_NOT_CONDITIONABLE" | "SCHEMA_NOT_FOUND" | "SCHEMA_DECLARES_NO_CONDITIONS" | "GROUPING_KEY_NOT_A_COLUMN" | "GROUPING_KEY_IS_SORT_COLUMN" | "CONDITIONAL_TARGET_MODE_UNSUPPORTED" | "UNIQUE_ID_NOT_IN_SCHEMA" | "VALUE_FORMAT_INVALID" | "MAPPING_EXPRESSION_FAILED" | "FROM_ROWS_EXPRESSION_FAILED" | "VALID_FROM_NOT_MAPPED" severity: "warning" | "blocking" columns?: Array<{ name: string entity?: string }> attributes?: Array<{ name: string entity?: string }> lines?: number[] subject?: string row?: number expected?: "number" | "text" | "decimal" | "date" } ``` ### `ErpImportValidation` Validate-phase summary: what the file will create, and whether it may be confirmed. Absent until the validate phase completes. No per-row detail is kept — a rejected file is corrected and imported again. ```ts type ErpImportValidation = { total_rows?: number blocking: number warnings: number entities: Record entity_details?: Array<{ mapping_index: number entity_schema: string business_key: Record variants?: number versions?: number condition_attributes?: string[] version_attribute?: string }> issues?: Array<{ code: "UNIQUE_ID_COLUMN_MISSING" | "MAPPED_COLUMN_MISSING" | "MALFORMED_ROW" | "INVALID_ENCODING" | "EMPTY_FILE" | "TOO_MANY_ROWS" | "BLANK_ROWS_SKIPPED" | "TIER_ROWS_NOT_GROUPED" | "TIER_BANDS_CONFLICT" | "CONDITION_VALUE_MISSING" | "VARIANT_VALUE_CONFLICT" | "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_NOT_IN_SCHEMA" | "IS_CONDITIONAL_NOT_CONSTANT" | "SCHEMA_NOT_CONDITIONABLE" | "SCHEMA_NOT_FOUND" | "SCHEMA_DECLARES_NO_CONDITIONS" | "GROUPING_KEY_NOT_A_COLUMN" | "GROUPING_KEY_IS_SORT_COLUMN" | "CONDITIONAL_TARGET_MODE_UNSUPPORTED" | "UNIQUE_ID_NOT_IN_SCHEMA" | "VALUE_FORMAT_INVALID" | "MAPPING_EXPRESSION_FAILED" | "FROM_ROWS_EXPRESSION_FAILED" | "VALID_FROM_NOT_MAPPED" severity: "warning" | "blocking" columns?: Array<{ name: { ... } entity?: { ... } }> attributes?: Array<{ name: { ... } entity?: { ... } }> lines?: number[] subject?: string row?: number expected?: "number" | "text" | "decimal" | "date" }> } ``` ### `ErpImportEntityDetail` One entity instance the import will write, attributed to the mapping target that produces it. ```ts type ErpImportEntityDetail = { mapping_index: number entity_schema: string business_key: Record variants?: number versions?: number condition_attributes?: string[] version_attribute?: string } ``` ### `ErpImportProgress` How far the currently running phase has got. Written at every batch boundary, so it advances during long runs rather than only at the end. `total_rows` is ABSENT during the validate phase until the file has been read to the end — there is deliberately no counting pass, since that would be a second u ```ts type ErpImportProgress = { processed_rows: number total_rows?: number events_published?: number } ``` ### `ErpImportError` Why the import failed — present if and only if status = FAILED. `code` is the translation key; for VALIDATION_BLOCKED the specifics are in `validation`. ```ts type ErpImportError = { code: "VALIDATION_BLOCKED" | "FILE_FORMAT_UNSUPPORTED" | "FILE_UNAVAILABLE" | "VALIDATE_TIMEOUT" | "IMPORT_TIMEOUT" | "USE_CASE_NOT_USABLE" | "IMPORT_NO_PROGRESS" | "TIER_ROWS_NOT_GROUPED" | "CHUNK_TOO_LARGE" | "INTERNAL_ERROR" message: string } ``` ### `ErpImportFilePreview` Sample of the file's first rows, using the same parser as `:validate`. Registration refuses a file it cannot read, so a created job always includes this. ```ts type ErpImportFilePreview = { columns: string[] rows: string[][] } ``` ### `ErpImportDownload` ```ts type ErpImportDownload = { download_url: string // uri filename: string expires_at: string // date-time } ``` ### `CreateErpImportResponse` ```ts type CreateErpImportResponse = { job: { import_id: string org_id: string created_by?: string integration_id?: string use_case_slug?: string format: "csv" | "xlsx" status: "PENDING" | "VALIDATING" | "READY" | "PROCESSING" | "IMPORTED" | "FAILED" | "CANCELLING" | "CANCELLED" s3_input_ref: { bucket: { ... } key: { ... } } size_bytes?: number column_count?: number validation?: { total_rows?: { ... } blocking: { ... } warnings: { ... } entities: { ... } entity_details?: { ... } issues?: { ... } } progress?: { processed_rows: { ... } total_rows?: { ... } events_published?: { ... } } error?: { code: { ... } message: { ... } } correlation_id?: string activity_id?: string created_at: string // date-time updated_at: string // date-time } preview?: { columns: string[] rows: string[][] } } ``` ### `ErpImportJob` ```ts type ErpImportJob = { import_id: string org_id: string created_by?: string integration_id?: string use_case_slug?: string format: "csv" | "xlsx" status: "PENDING" | "VALIDATING" | "READY" | "PROCESSING" | "IMPORTED" | "FAILED" | "CANCELLING" | "CANCELLED" s3_input_ref: { bucket: string key: string } size_bytes?: number column_count?: number validation?: { total_rows?: number blocking: number warnings: number entities: Record entity_details?: Array<{ mapping_index: { ... } entity_schema: { ... } business_key: { ... } variants?: { ... } versions?: { ... } condition_attributes?: { ... } version_attribute?: { ... } }> issues?: Array<{ code: { ... } severity: { ... } columns?: { ... } attributes?: { ... } lines?: { ... } subject?: { ... } row?: { ... } expected?: { ... } }> } progress?: { processed_rows: number total_rows?: number events_published?: number } error?: { code: "VALIDATION_BLOCKED" | "FILE_FORMAT_UNSUPPORTED" | "FILE_UNAVAILABLE" | "VALIDATE_TIMEOUT" | "IMPORT_TIMEOUT" | "USE_CASE_NOT_USABLE" | "IMPORT_NO_PROGRESS" | "TIER_ROWS_NOT_GROUPED" | "CHUNK_TOO_LARGE" | "INTERNAL_ERROR" message: string } correlation_id?: string activity_id?: string created_at: string // date-time updated_at: string // date-time } ``` ### `ErpImportList` ```ts type ErpImportList = { results: Array<{ import_id: string org_id: string created_by?: string integration_id?: string use_case_slug?: string format: "csv" | "xlsx" status: "PENDING" | "VALIDATING" | "READY" | "PROCESSING" | "IMPORTED" | "FAILED" | "CANCELLING" | "CANCELLED" s3_input_ref: { bucket: { ... } key: { ... } } size_bytes?: number column_count?: number validation?: { total_rows?: { ... } blocking: { ... } warnings: { ... } entities: { ... } entity_details?: { ... } issues?: { ... } } progress?: { processed_rows: { ... } total_rows?: { ... } events_published?: { ... } } error?: { code: { ... } message: { ... } } correlation_id?: string activity_id?: string created_at: string // date-time updated_at: string // date-time }> next_cursor?: string } ``` ### `NotificationHistoryItem` A single notification-history row (one real notification decision). ```ts type NotificationHistoryItem = { id: string type: string state_transition?: string severity: "error" | "warning" | "info" title: string occurred_at: string // date-time notified: boolean suppressed_reason?: "muted" | "debounced" | "recipient_opt_out" recipients: string[] context: Record created_at: string // date-time } ``` ### `NotificationHistoryResponse` ```ts type NotificationHistoryResponse = { history: Array<{ id: string type: string state_transition?: string severity: "error" | "warning" | "info" title: string occurred_at: string // date-time notified: boolean suppressed_reason?: "muted" | "debounced" | "recipient_opt_out" recipients: string[] context: Record created_at: string // date-time }> next_cursor?: string } ``` ### `TestNotificationRequest` ```ts type TestNotificationRequest = { kind: "alert" | "digest" type?: string channels?: "email" | "in_app"[] } ``` ### `TestNotificationResponse` ```ts type TestNotificationResponse = { sent: boolean recipient: string channels: string[] notification_id?: string } ``` ### `NotificationStatusResponse` ```ts type NotificationStatusResponse = { health: "healthy" | "alerting" | "muted" evaluated_at?: string // date-time rules: Array<{ rule_id: string state: "ok" | "alerting" | "recovered" last_fired_at?: string // date-time last_cleared_at?: string // date-time last_evaluation?: { evaluated_at: { ... } observed: { ... } threshold?: { ... } suppressed_reason?: { ... } } baseline?: { is_mature: { ... } computed_at?: { ... } median?: { ... } mad?: { ... } upper?: { ... } buckets?: { ... } } }> } ``` ### `NotificationRuleStatus` ```ts type NotificationRuleStatus = { rule_id: string state: "ok" | "alerting" | "recovered" last_fired_at?: string // date-time last_cleared_at?: string // date-time last_evaluation?: { evaluated_at: string // date-time observed: number threshold?: number suppressed_reason?: "sample_size" } baseline?: { is_mature: boolean computed_at?: string // date-time median?: number mad?: number upper?: number buckets?: Array<{ dow: { ... } hour: { ... } median: { ... } mad: { ... } }> } } ``` ### `RuleBaselineStatus` ```ts type RuleBaselineStatus = { is_mature: boolean computed_at?: string // date-time median?: number mad?: number upper?: number buckets?: Array<{ dow: number hour: number median: number mad: number }> } ``` ### `RuleBaselineBucket` ```ts type RuleBaselineBucket = { dow: number hour: number median: number mad: number } ``` ### `ErrorResponseBase` ```ts type ErrorResponseBase = { code?: string message?: string } ``` ### `ErpEvent` ```ts type ErpEvent = { event_type: "CREATE" | "UPDATE" | "DELETE" object_type: string timestamp: string // date-time format: "json" | "xml" payload: string | Record deduplication_id?: string correlation_id?: string use_case_id?: string } ``` ### `ErpUpdatesEventsV2Request` ```ts type ErpUpdatesEventsV2Request = { integration_id: string // uuid correlation_id?: string events: Array<{ event_type: "CREATE" | "UPDATE" | "DELETE" object_type: string timestamp: string // date-time format: "json" | "xml" payload: string | Record deduplication_id?: string correlation_id?: string use_case_id?: string }> } ``` ### `ErpEventV3` ```ts type ErpEventV3 = unknown | unknown ``` ### `ErpUpdatesEventsV3Request` ```ts type ErpUpdatesEventsV3Request = { integration_id: string // uuid correlation_id?: string group_id?: string interactive?: boolean correlation_complete?: boolean events: unknown | unknown[] } ``` ### `ErpUpdateProcessedEntity` An entity an interactive event wrote. ```ts type ErpUpdateProcessedEntity = { slug: string _id: string operation: "created" | "updated" | "deleted" | "unchanged" unique_ids: Record } ``` ### `CorrelationCloseResult` What became of the request's `correlation_complete`. Present exactly when the request carried `correlation_complete: true`; absent otherwise. ```ts type CorrelationCloseResult = { outcome: "applied" | "rate_limited" | "ignored" reasons?: "retry_requested" | "queue_refused" | "events_under_own_correlation_ids" | "events_duplicate" | "events_not_configured" | "events_not_interactive" | "events_unrecorded" | "rate_limited" | "rate_limit_unavailable" | "other_integration" | "close_failed" | "interactive_unavailable"[] message?: string } ``` ### `ErpUpdateProcessingError` A failure nothing will retry. ```ts type ErpUpdateProcessingError = { code: string message: string event_id?: string occurred_at: string // date-time after_completion?: boolean } ``` ### `ErpUpdateEventStatus` One interactive event's processing record. ```ts type ErpUpdateEventStatus = { event_id: string correlation_id?: string integration_id?: string status: "accepted" | "processing" | "done" | "partial" | "error" lane: "interactive" | "priority" | "default" | "deferred" use_case_id?: string use_case_slug?: string event_name?: string ingested_at: string // date-time mapped_at?: string // date-time done_at?: string // date-time writes_total: number writes_done: number entities: Array<{ slug: string _id: string operation: "created" | "updated" | "deleted" | "unchanged" unique_ids: Record }> entities_omitted?: number errors: Array<{ code: string message: string event_id?: string occurred_at: string // date-time after_completion?: boolean }> errors_total: number } ``` ### `CorrelationUseCaseCounts` How many of a correlation's events belong to one use case, and how they ended. ```ts type CorrelationUseCaseCounts = { use_case_slug: string received: number done: number error: number } ``` ### `CorrelationStatus` One correlation's summary. ```ts type CorrelationStatus = { correlation_id: string integration_id?: string closed: boolean closed_at?: string // date-time complete: boolean completed_at?: string // date-time events_received: number events_done: number late_events: number first_ingested_at?: string // date-time last_done_at?: string // date-time use_cases: Array<{ use_case_slug: string received: number done: number error: number }> entities: Array<{ slug: string _id: string operation: "created" | "updated" | "deleted" | "unchanged" unique_ids: Record }> entities_omitted?: number errors: Array<{ code: string message: string event_id?: string occurred_at: string // date-time after_completion?: boolean }> errors_total: number } ``` ### `CorrelationWaitResult` ```ts type CorrelationWaitResult = { correlation_id: string integration_id?: string closed: boolean closed_at?: string // date-time complete: boolean completed_at?: string // date-time events_received: number events_done: number late_events: number first_ingested_at?: string // date-time last_done_at?: string // date-time use_cases: Array<{ use_case_slug: string received: number done: number error: number }> entities: Array<{ slug: string _id: string operation: "created" | "updated" | "deleted" | "unchanged" unique_ids: Record }> entities_omitted?: number errors: Array<{ code: string message: string event_id?: string occurred_at: string // date-time after_completion?: boolean }> errors_total: number completion: "requirements_met" | "complete" | "timeout" | "error" undecided_entity_requirements?: string[] } ``` ### `CorrelationWaitBadRequest` ```ts type CorrelationWaitBadRequest = { message: string slug?: string rejected_key?: string use_case_slug?: string allowed_keys?: string[] } ``` ### `CorrelationStatusList` ```ts type CorrelationStatusList = { results: Array<{ correlation_id: string integration_id?: string closed: boolean closed_at?: string // date-time complete: boolean completed_at?: string // date-time events_received: number events_done: number late_events: number first_ingested_at?: string // date-time last_done_at?: string // date-time use_cases: Array<{ use_case_slug: { ... } received: { ... } done: { ... } error: { ... } }> entities: Array<{ slug: { ... } _id: { ... } operation: { ... } unique_ids: { ... } }> entities_omitted?: number errors: Array<{ code: { ... } message: { ... } event_id?: { ... } occurred_at: { ... } after_completion?: { ... } }> errors_total: number }> next_cursor: string horizon_days: number } ``` ### `TriggerErpActionRequest` ```ts type TriggerErpActionRequest = { execution_id: string org_id: string webhook_id: string flow_id: string created_at: string // date-time action_id: string flow_action_id: string flow_name: string activity_id: string entity_id: string } ``` ### `TriggerWebhookResp` ```ts type TriggerWebhookResp = { status_code?: string message?: string body?: object code?: string status?: "succeeded" | "failed" start_date?: string end_date?: string event_id?: string } ``` ### `IntegrationEditableFields` ```ts type IntegrationEditableFields = { name?: string description?: string access_token_ids?: string[] app_ids?: string[] environment_config?: Array<{ key: string label: string type: "String" | "SecretString" description?: string required?: boolean order?: number }> maps?: Array<{ key: string label: string description?: string value: Record }> settings?: { autoRefresh?: { enabled?: { ... } freshnessThresholdMinutes?: { ... } } notifications?: { enabled: { ... } recipients: { ... } defaultChannels: { ... } monitoredUseCases?: { ... } monitoredCodes?: { ... } rules: { ... } digest: { ... } muteUntil?: { ... } } } integration_type?: "erp" | "connector" connector_config?: { base_url?: string auth?: { type?: { ... } token_url?: { ... } client_id?: { ... } client_secret?: { ... } scope?: { ... } audience?: { ... } resource?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } api_key_header?: { ... } api_key?: { ... } token?: { ... } } types_versions?: Array<{ version: { ... } package_name: { ... } generated_at: { ... } generated_by: { ... } status: { ... } }> latest_types_version?: string latest_types_package_name?: string } protected?: boolean _manifest?: string[] } ``` ### `ConnectorConfig` Shared configuration for connector-type integrations ```ts type ConnectorConfig = { base_url?: string auth?: { type?: "oauth2_client_credentials" | "api_key" | "bearer" token_url?: string client_id?: string client_secret?: string scope?: string audience?: string resource?: string body_params?: Record headers?: Record query_params?: Record api_key_header?: string api_key?: string token?: string } types_versions?: Array<{ version: string package_name: string generated_at: string // date-time generated_by: string status: "active" | "deprecated" }> latest_types_version?: string latest_types_package_name?: string } ``` ### `ManagedCallAuth` Authentication configuration for managed call requests ```ts type ManagedCallAuth = { type?: "oauth2_client_credentials" | "api_key" | "bearer" token_url?: string client_id?: string client_secret?: string scope?: string audience?: string resource?: string body_params?: Record headers?: Record query_params?: Record api_key_header?: string api_key?: string token?: string } ``` ### `Integration` ```ts type Integration = { id: string // uuid orgId: string created_at: string // date-time updated_at: string // date-time name: string description?: string access_token_ids?: string[] app_ids?: string[] environment_config?: Array<{ key: string label: string type: "String" | "SecretString" description?: string required?: boolean order?: number }> maps?: Array<{ key: string label: string description?: string value: Record }> settings?: { autoRefresh?: { enabled?: { ... } freshnessThresholdMinutes?: { ... } } notifications?: { enabled: { ... } recipients: { ... } defaultChannels: { ... } monitoredUseCases?: { ... } monitoredCodes?: { ... } rules: { ... } digest: { ... } muteUntil?: { ... } } } integration_type?: "erp" | "connector" connector_config?: { base_url?: string auth?: { type?: { ... } token_url?: { ... } client_id?: { ... } client_secret?: { ... } scope?: { ... } audience?: { ... } resource?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } api_key_header?: { ... } api_key?: { ... } token?: { ... } } types_versions?: Array<{ version: { ... } package_name: { ... } generated_at: { ... } generated_by: { ... } status: { ... } }> latest_types_version?: string latest_types_package_name?: string } protected?: boolean _manifest?: string[] } ``` ### `CreateIntegrationRequest` ```ts type CreateIntegrationRequest = { name: string description?: string access_token_ids?: string[] app_ids?: string[] environment_config?: Array<{ key: string label: string type: "String" | "SecretString" description?: string required?: boolean order?: number }> maps?: Array<{ key: string label: string description?: string value: Record }> settings?: { autoRefresh?: { enabled?: { ... } freshnessThresholdMinutes?: { ... } } notifications?: { enabled: { ... } recipients: { ... } defaultChannels: { ... } monitoredUseCases?: { ... } monitoredCodes?: { ... } rules: { ... } digest: { ... } muteUntil?: { ... } } } integration_type?: "erp" | "connector" connector_config?: { base_url?: string auth?: { type?: { ... } token_url?: { ... } client_id?: { ... } client_secret?: { ... } scope?: { ... } audience?: { ... } resource?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } api_key_header?: { ... } api_key?: { ... } token?: { ... } } types_versions?: Array<{ version: { ... } package_name: { ... } generated_at: { ... } generated_by: { ... } status: { ... } }> latest_types_version?: string latest_types_package_name?: string } protected?: boolean _manifest?: string[] } ``` ### `UpdateIntegrationRequest` ```ts type UpdateIntegrationRequest = { name?: string description?: string access_token_ids?: string[] app_ids?: string[] environment_config?: Array<{ key: string label: string type: "String" | "SecretString" description?: string required?: boolean order?: number }> maps?: Array<{ key: string label: string description?: string value: Record }> settings?: { autoRefresh?: { enabled?: { ... } freshnessThresholdMinutes?: { ... } } notifications?: { enabled: { ... } recipients: { ... } defaultChannels: { ... } monitoredUseCases?: { ... } monitoredCodes?: { ... } rules: { ... } digest: { ... } muteUntil?: { ... } } } integration_type?: "erp" | "connector" connector_config?: { base_url?: string auth?: { type?: { ... } token_url?: { ... } client_id?: { ... } client_secret?: { ... } scope?: { ... } audience?: { ... } resource?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } api_key_header?: { ... } api_key?: { ... } token?: { ... } } types_versions?: Array<{ version: { ... } package_name: { ... } generated_at: { ... } generated_by: { ... } status: { ... } }> latest_types_version?: string latest_types_package_name?: string } protected?: boolean _manifest?: string[] } ``` ### `IntegrationMap` A flat key/value map stored as an Environments API variable of type `JSON`. Values must be strings, numbers, booleans or null; the serialised map must not exceed 32 KB. ```ts type IntegrationMap = { key: string label: string description?: string value: Record } ``` ### `EnvironmentFieldConfig` ```ts type EnvironmentFieldConfig = { key: string label: string type: "String" | "SecretString" description?: string required?: boolean order?: number } ``` ### `IntegrationSettings` Settings for the integration ```ts type IntegrationSettings = { autoRefresh?: { enabled?: boolean freshnessThresholdMinutes?: number } notifications?: { enabled: boolean recipients: Array<{ user_id: { ... } }> defaultChannels: { email: { ... } in_app: { ... } } monitoredUseCases?: string[] monitoredCodes?: string[] rules: Array<{ id?: { ... } name?: { ... } type: { ... } enabled: { ... } channels?: { ... } codes?: { ... } threshold?: { ... } sensitivity?: { ... } fallbackThreshold?: { ... } window?: { ... } minSampleSize?: { ... } quietPeriod?: { ... } }> digest: { enabled: { ... } frequency: { ... } dayOfWeek?: { ... } timeOfDay: { ... } timezone: { ... } channels: { ... } includeHealthy: { ... } skipIfEmpty: { ... } } muteUntil?: string // date-time } } ``` ### `AutoRefreshSettings` Auto-refresh settings for keeping integration data fresh ```ts type AutoRefreshSettings = { enabled?: boolean freshnessThresholdMinutes?: number } ``` ### `IntegrationNotificationConfig` Integration monitoring notification configuration. Rides Integration.settings.notifications (camelCase) and surfaces on both v1 and v2 GET/PUT. Unknown keys are stripped server-side to stay forward-compatible with deferred (V2) rule types. ```ts type IntegrationNotificationConfig = { enabled: boolean recipients: Array<{ user_id: string }> defaultChannels: { email: boolean in_app: boolean } monitoredUseCases?: string[] monitoredCodes?: string[] rules: Array<{ id?: string name?: string type: "critical_error" | "error_threshold" | "warning_threshold" | "success_rate_drop" | "recovery" | "silence" enabled: boolean channels?: { email: { ... } in_app: { ... } } codes?: string[] threshold?: number | "auto" sensitivity?: "low" | "medium" | "high" fallbackThreshold?: number window?: string minSampleSize?: number quietPeriod?: string }> digest: { enabled: boolean frequency: "daily" | "weekly" dayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6 timeOfDay: string timezone: string channels: { email: { ... } in_app: { ... } } includeHealthy: boolean skipIfEmpty: boolean } muteUntil?: string // date-time } ``` ### `NotificationRecipient` A configured recipient. Only the epilot user_id is stored. ```ts type NotificationRecipient = { user_id: string } ``` ### `NotificationChannelSet` Delivery channel toggles. New channels added in svc-notification-api inherit here. ```ts type NotificationChannelSet = { email: boolean in_app: boolean } ``` ### `NotificationRule` A single notification rule. Only the params relevant to a given type are set. The id is optional on write: the server mints a ULID when omitted and preserves a supplied id verbatim (a stable id keeps a rule's AlertState across config saves). ```ts type NotificationRule = { id?: string name?: string type: "critical_error" | "error_threshold" | "warning_threshold" | "success_rate_drop" | "recovery" | "silence" enabled: boolean channels?: { email: boolean in_app: boolean } codes?: string[] threshold?: number | "auto" sensitivity?: "low" | "medium" | "high" fallbackThreshold?: number window?: string minSampleSize?: number quietPeriod?: string } ``` ### `NotificationDigestConfig` Digest schedule and content configuration. ```ts type NotificationDigestConfig = { enabled: boolean frequency: "daily" | "weekly" dayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6 timeOfDay: string timezone: string channels: { email: boolean in_app: boolean } includeHealthy: boolean skipIfEmpty: boolean } ``` ### `SetIntegrationAppMappingRequest` ```ts type SetIntegrationAppMappingRequest = { app_id: string // uuid component_id: string // uuid overwrite?: boolean } ``` ### `DeleteIntegrationAppMappingRequest` ```ts type DeleteIntegrationAppMappingRequest = { app_id: string // uuid component_id: string // uuid } ``` ### `IntegrationAppMapping` ```ts type IntegrationAppMapping = { integration_id: string // uuid } ``` ### `IntegrationWithUseCases` ```ts type IntegrationWithUseCases = { use_cases: Array<{ id: string // uuid integrationId: string // uuid name: string slug?: string type: "inbound" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { direct?: { ... } interactive?: { ... } entities?: { ... } meter_readings?: { ... } } } | { id: string // uuid integrationId: string // uuid name: string slug?: string type: "outbound" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { event_catalog_event: { ... } event_filter?: { ... } mappings: { ... } ack_tracking?: { ... } } } | { id: string // uuid integrationId: string // uuid name: string slug?: string type: "file_proxy" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { direction?: { ... } upload?: { ... } fan_out?: { ... } secure_proxy?: { ... } auth?: { ... } params?: { ... } allowed_origins?: { ... } steps: { ... } response?: { ... } prevent_indirect_serving?: { ... } } } | { id: string // uuid integrationId: string // uuid name: string slug?: string type: "managed_call" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { operation: { ... } request_mapping?: { ... } response_mapping?: { ... } inbound_use_case_slug?: { ... } } type_annotations?: { request?: { ... } response?: { ... } } types_locked?: boolean } | { id: string // uuid integrationId: string // uuid name: string slug?: string type: "secure_proxy" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { vpc_mode: { ... } allowed_domains?: { ... } allowed_ips?: { ... } } }> } ``` ### `UpsertIntegrationWithUseCasesRequest` ```ts type UpsertIntegrationWithUseCasesRequest = { name: string description?: string access_token_ids?: string[] app_ids?: string[] environment_config?: Array<{ key: string label: string type: "String" | "SecretString" description?: string required?: boolean order?: number }> maps?: Array<{ key: string label: string description?: string value: Record }> settings?: { autoRefresh?: { enabled?: { ... } freshnessThresholdMinutes?: { ... } } notifications?: { enabled: { ... } recipients: { ... } defaultChannels: { ... } monitoredUseCases?: { ... } monitoredCodes?: { ... } rules: { ... } digest: { ... } muteUntil?: { ... } } } integration_type?: "erp" | "connector" connector_config?: { base_url?: string auth?: { type?: { ... } token_url?: { ... } client_id?: { ... } client_secret?: { ... } scope?: { ... } audience?: { ... } resource?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } api_key_header?: { ... } api_key?: { ... } token?: { ... } } types_versions?: Array<{ version: { ... } package_name: { ... } generated_at: { ... } generated_by: { ... } status: { ... } }> latest_types_version?: string latest_types_package_name?: string } protected?: boolean _manifest?: string[] use_cases?: Array<{ id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "inbound" configuration?: { direct?: { ... } interactive?: { ... } entities?: { ... } meter_readings?: { ... } } } | { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "outbound" configuration?: { event_catalog_event: { ... } event_filter?: { ... } mappings: { ... } ack_tracking?: { ... } } } | { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "file_proxy" configuration?: { direction?: { ... } // ... } ``` ### `InboundIntegrationEventConfiguration` Configuration for inbound use cases (ERP to epilot) ```ts type InboundIntegrationEventConfiguration = { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: string unique_ids: string[] jsonataExpression?: string enabled?: boolean | string mode?: "upsert" | "delete" | "purge" | "upsert-prune-scope-purge" | "upsert-prune-scope-delete" scope?: { scope_mode: { ... } schema?: { ... } unique_ids?: { ... } query?: { ... } } fields?: Array<{ attribute: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } _type?: { ... } enabled?: { ... } relations?: { ... } relation_refs?: { ... } file_proxy_url?: { ... } portal_ref?: { ... } env_var_ref?: { ... } }> conditional?: { from_rows: { ... } } sharing?: { partners: { ... } } }> meter_readings?: Array<{ jsonataExpression?: string reading_matching?: "external_id" | "strict-date" mode?: "upsert" | "delete" | "upsert-prune-scope" scope?: { source?: { ... } } meter: { unique_ids: { ... } } meter_counter?: { unique_ids: { ... } } fields: Array<{ attribute: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } _type?: { ... } enabled?: { ... } relations?: { ... } relation_refs?: { ... } file_proxy_url?: { ... } portal_ref?: { ... } env_var_ref?: { ... } }> }> } ``` ### `OutboundIntegrationEventConfiguration` Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings. ```ts type OutboundIntegrationEventConfiguration = { event_catalog_event: string event_filter?: string mappings: Array<{ id?: string // uuid name: string jsonata_expression?: string enabled: boolean delivery: { type: { ... } webhook_id: { ... } webhook_name?: { ... } webhook_url?: { ... } } | { type: { ... } retention_days?: { ... } poison_policy?: { ... } max_delivery_attempts?: { ... } } | { type: { ... } use_case_slug: { ... } } created_at?: string // date-time updated_at?: string // date-time }> ack_tracking?: "on" | "off" } ``` ### `IntegrationEntity` ```ts type IntegrationEntity = { entity_schema: string unique_ids: string[] jsonataExpression?: string enabled?: boolean | string mode?: "upsert" | "delete" | "purge" | "upsert-prune-scope-purge" | "upsert-prune-scope-delete" scope?: { scope_mode: "relations" | "query" schema?: string unique_ids?: Array<{ attribute: { ... } _type?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } }> query?: Array<{ attribute: { ... } _type?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } }> } fields?: Array<{ attribute: string field?: string jsonataExpression?: string constant?: unknown _type?: "email" | "phone" enabled?: boolean | string relations?: { operation: { ... } items?: { ... } jsonataExpression?: { ... } } relation_refs?: { operation: { ... } items?: { ... } jsonataExpression?: { ... } } file_proxy_url?: { use_case_slug: { ... } params?: { ... } } | { use_case_id: { ... } params?: { ... } } portal_ref?: { filter?: { ... } select?: { ... } return?: { ... } } | { filter?: { ... } select?: { ... } return: { ... } jsonataExpression: { ... } } env_var_ref?: { key: { ... } default?: { ... } return?: { ... } } | { key: { ... } default?: { ... } return: { ... } jsonataExpression: { ... } } }> conditional?: { from_rows: Array<{ attribute: { ... } sort_by: { ... } item: { ... } }> } sharing?: { partners: Array<{ partner_org_id: { ... } enabled?: { ... } }> } } ``` ### `IntegrationEntitySharing` Keeps the mapped entity's sharing with partner organizations in sync. After the entity is written, it is shared with every listed partner whose `enabled` is true and unshared from every listed partner whose `enabled` is false. Changes are computed against the entity's current `_acl`, so a repeated e ```ts type IntegrationEntitySharing = { partners: Array<{ partner_org_id: string enabled?: boolean | string }> } ``` ### `IntegrationEntitySharingPartner` ```ts type IntegrationEntitySharingPartner = { partner_org_id: string enabled?: boolean | string } ``` ### `IntegrationEntityConditional` Conditional Pricing extras for this target, used when it writes a conditional entity (a Product, Price or Coupon carrying context-dependent variants). The conditions themselves are declared on the entity schema, not here. ```ts type IntegrationEntityConditional = { from_rows: Array<{ attribute: string sort_by: { field: { ... } } | { constant: { ... } } | { jsonataExpression: { ... } } item: Record }> } ``` ### `IntegrationEntityFromRows` Build one array attribute from the rows of one variant-version, ordered by a column. A commodity file carries one row per consumption band, while a variant-version holds exactly one `tiers` array. ```ts type IntegrationEntityFromRows = { attribute: string sort_by: { field: string } | { constant: unknown } | { jsonataExpression: string } item: Record } ``` ### `MappedFieldValue` One mapped value. Exactly one of field, constant or jsonataExpression must be set — the same three forms `IntegrationEntityField` accepts. ```ts type MappedFieldValue = { field: string } | { constant: unknown } | { jsonataExpression: string } ``` ### `IntegrationMeterReading` ```ts type IntegrationMeterReading = { jsonataExpression?: string reading_matching?: "external_id" | "strict-date" mode?: "upsert" | "delete" | "upsert-prune-scope" scope?: { source?: string } meter: { unique_ids: Array<{ attribute: { ... } _type?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } }> } meter_counter?: { unique_ids: Array<{ attribute: { ... } _type?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } }> } fields: Array<{ attribute: string field?: string jsonataExpression?: string constant?: unknown _type?: "email" | "phone" enabled?: boolean | string relations?: { operation: { ... } items?: { ... } jsonataExpression?: { ... } } relation_refs?: { operation: { ... } items?: { ... } jsonataExpression?: { ... } } file_proxy_url?: { use_case_slug: { ... } params?: { ... } } | { use_case_id: { ... } params?: { ... } } portal_ref?: { filter?: { ... } select?: { ... } return?: { ... } } | { filter?: { ... } select?: { ... } return: { ... } jsonataExpression: { ... } } env_var_ref?: { key: { ... } default?: { ... } return?: { ... } } | { key: { ... } default?: { ... } return: { ... } jsonataExpression: { ... } } }> } ``` ### `PruneScopeConfig` Scope configuration for upsert-prune-scope modes. Defines how to find entities that should be pruned if not in the upsert payload. The scope is resolved against the original event payload (not individual array items). ```ts type PruneScopeConfig = { scope_mode: "relations" | "query" schema?: string unique_ids?: Array<{ attribute: string _type?: "email" | "phone" field?: string jsonataExpression?: string constant?: unknown }> query?: Array<{ attribute: string _type?: "email" | "phone" field?: string jsonataExpression?: string constant?: unknown }> } ``` ### `MeterReadingPruneScopeConfig` Scope configuration for meter reading upsert-prune-scope mode. The scope is all readings for the same meter + counter. ```ts type MeterReadingPruneScopeConfig = { source?: string } ``` ### `MeterUniqueIdsConfig` ```ts type MeterUniqueIdsConfig = { unique_ids: Array<{ attribute: string _type?: "email" | "phone" field?: string jsonataExpression?: string constant?: unknown }> } ``` ### `IntegrationEntityField` ```ts type IntegrationEntityField = { attribute: string field?: string jsonataExpression?: string constant?: unknown _type?: "email" | "phone" enabled?: boolean | string relations?: { operation: "_set" | "_append" | "_append_all" items?: Array<{ entity_schema: { ... } _tags?: { ... } unique_ids: { ... } required?: { ... } }> jsonataExpression?: string } relation_refs?: { operation: "_set" | "_append" | "_append_all" items?: Array<{ entity_schema: { ... } unique_ids: { ... } path: { ... } value: { ... } }> jsonataExpression?: string } file_proxy_url?: { use_case_slug: string params?: Record } | { use_case_id: string params?: Record } portal_ref?: { filter?: { origin?: { ... } enabled?: { ... } is_dummy?: { ... } is_epilot_domain?: { ... } name?: { ... } domain?: { ... } } select?: "single" | "all" return?: "portal_id" | "origin" | "domain" | "name" } | { filter?: { origin?: { ... } enabled?: { ... } is_dummy?: { ... } is_epilot_domain?: { ... } name?: { ... } domain?: { ... } } select?: "single" | "all" return: "jsonata" jsonataExpression: string } env_var_ref?: { key: string default?: string return?: "value" } | { key: string default?: string return: "jsonata" jsonataExpression: string } } ``` ### `FileProxyUrlParam` Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set. ```ts type FileProxyUrlParam = { field: string } | { constant: unknown } | { jsonataExpression: string } ``` ### `FileProxyUrlParams` Custom query parameters. Keys become URL param names, values resolved from payload. ```ts type FileProxyUrlParams = Record ``` ### `FileProxyUrlConfig` Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments. ```ts type FileProxyUrlConfig = { use_case_slug: string params?: Record } | { use_case_id: string params?: Record } ``` ### `PortalOrigin` Origin/type of an epilot portal configuration. ```ts type PortalOrigin = "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" ``` ### `PortalRefFilter` Filter applied to the org's portal configurations before selection. All filters default to "match any" except `enabled` (default `true`) and `is_dummy` (default `false`). Set `enabled` or `is_dummy` to `null` to opt out of the default. ```ts type PortalRefFilter = { origin?: "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" | "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"[] enabled?: boolean is_dummy?: boolean is_epilot_domain?: boolean name?: string domain?: string } ``` ### `PortalRefConfig` Resolves to a property of one of the calling organization's epilot portal configurations at runtime, replacing hard-coded environment-specific portal UUIDs in inbound mappings. Matched portals are sorted ascending by `(_created_at, portal_id)`; portals without `_created_at` sort first (treated as ol ```ts type PortalRefConfig = { filter?: { origin?: "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" | "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"[] enabled?: boolean is_dummy?: boolean is_epilot_domain?: boolean name?: string domain?: string } select?: "single" | "all" return?: "portal_id" | "origin" | "domain" | "name" } | { filter?: { origin?: "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL" | "END_CUSTOMER_PORTAL" | "INSTALLER_PORTAL" | "B2B_PORTAL" | "ADDITIONAL_PORTAL"[] enabled?: boolean is_dummy?: boolean is_epilot_domain?: boolean name?: string domain?: string } select?: "single" | "all" return: "jsonata" jsonataExpression: string } ``` ### `EnvVarRefConfig` Resolves to an org-scoped environment variable from the epilot environments-api service at runtime, replacing hard-coded environment-specific values (URLs, prefixes, identifiers) in inbound mappings. Secrets (`SecretString` values) are never exposed; the runtime treats both "missing key" and "secret ```ts type EnvVarRefConfig = { key: string default?: string return?: "value" } | { key: string default?: string return: "jsonata" jsonataExpression: string } ``` ### `EmbeddedUseCaseRequest` ```ts type EmbeddedUseCaseRequest = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } | { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } | { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } // ... } ``` ### `EmbeddedUseCaseRequestBase` ```ts type EmbeddedUseCaseRequestBase = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string } ``` ### `EmbeddedInboundUseCaseRequest` ```ts type EmbeddedInboundUseCaseRequest = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } ``` ### `EmbeddedOutboundUseCaseRequest` ```ts type EmbeddedOutboundUseCaseRequest = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } ``` ### `EmbeddedFileProxyUseCaseRequest` ```ts type EmbeddedFileProxyUseCaseRequest = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } encoding: { ... } filename?: { ... } content_type?: { ... } } prevent_indirect_serving?: boolean } } ``` ### `EmbeddedManagedCallUseCaseRequest` ```ts type EmbeddedManagedCallUseCaseRequest = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "managed_call" configuration?: { operation: { method: { ... } path: { ... } headers?: { ... } query_params?: { ... } } request_mapping?: string response_mapping?: string inbound_use_case_slug?: string } } ``` ### `EmbeddedSecureProxyUseCaseRequest` ```ts type EmbeddedSecureProxyUseCaseRequest = { id?: string // uuid name: string slug?: string enabled: boolean change_description?: string type: "secure_proxy" configuration?: { vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] } } ``` ### `UseCaseBase` ```ts type UseCaseBase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time } ``` ### `InboundUseCase` ```ts type InboundUseCase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "inbound" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } ``` ### `OutboundUseCase` ```ts type OutboundUseCase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "outbound" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } ``` ### `FileProxyUseCase` ```ts type FileProxyUseCase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "file_proxy" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } encoding: { ... } filename?: { ... } content_type?: { ... } } prevent_indirect_serving?: boolean } } ``` ### `ManagedCallUseCase` ```ts type ManagedCallUseCase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "managed_call" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { operation: { method: { ... } path: { ... } headers?: { ... } query_params?: { ... } } request_mapping?: string response_mapping?: string inbound_use_case_slug?: string } type_annotations?: { request?: Record response?: Record } types_locked?: boolean } ``` ### `SecureProxyUseCase` ```ts type SecureProxyUseCase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "secure_proxy" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] } } ``` ### `UseCase` ```ts type UseCase = { id: string // uuid integrationId: string // uuid name: string slug?: string type: "inbound" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } | { id: string // uuid integrationId: string // uuid name: string slug?: string type: "outbound" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } | { id: string // uuid integrationId: string // uuid name: string slug?: string type: "file_proxy" enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } // ... } ``` ### `CreateUseCaseRequest` ```ts type CreateUseCaseRequest = { name: string slug: string enabled: boolean type: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } | { name: string slug: string enabled: boolean type: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } | { name: string slug: string enabled: boolean type: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } encoding: { ... } filename?: { ... } content_type?: { ... } // ... } ``` ### `CreateUseCaseRequestBase` ```ts type CreateUseCaseRequestBase = { name: string slug: string enabled: boolean } ``` ### `CreateInboundUseCaseRequest` ```ts type CreateInboundUseCaseRequest = { name: string slug: string enabled: boolean type: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } ``` ### `CreateOutboundUseCaseRequest` ```ts type CreateOutboundUseCaseRequest = { name: string slug: string enabled: boolean type: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } ``` ### `CreateFileProxyUseCaseRequest` ```ts type CreateFileProxyUseCaseRequest = { name: string slug: string enabled: boolean type: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } encoding: { ... } filename?: { ... } content_type?: { ... } } prevent_indirect_serving?: boolean } } ``` ### `CreateManagedCallUseCaseRequest` ```ts type CreateManagedCallUseCaseRequest = { name: string slug: string enabled: boolean type: "managed_call" configuration?: { operation: { method: { ... } path: { ... } headers?: { ... } query_params?: { ... } } request_mapping?: string response_mapping?: string inbound_use_case_slug?: string } } ``` ### `CreateSecureProxyUseCaseRequest` ```ts type CreateSecureProxyUseCaseRequest = { name: string slug: string enabled: boolean type: "secure_proxy" configuration?: { vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] } } ``` ### `UpdateUseCaseRequest` ```ts type UpdateUseCaseRequest = { name?: string slug?: string enabled?: boolean change_description?: string type?: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } | { name?: string slug?: string enabled?: boolean change_description?: string type?: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } | { name?: string slug?: string enabled?: boolean change_description?: string type?: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } // ... } ``` ### `UpdateUseCaseRequestBase` ```ts type UpdateUseCaseRequestBase = { name?: string slug?: string enabled?: boolean change_description?: string } ``` ### `UpdateInboundUseCaseRequest` ```ts type UpdateInboundUseCaseRequest = { name?: string slug?: string enabled?: boolean change_description?: string type?: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } ``` ### `UpdateOutboundUseCaseRequest` ```ts type UpdateOutboundUseCaseRequest = { name?: string slug?: string enabled?: boolean change_description?: string type?: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } ``` ### `UpdateFileProxyUseCaseRequest` ```ts type UpdateFileProxyUseCaseRequest = { name?: string slug?: string enabled?: boolean change_description?: string type?: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } encoding: { ... } filename?: { ... } content_type?: { ... } } prevent_indirect_serving?: boolean } } ``` ### `UpdateManagedCallUseCaseRequest` ```ts type UpdateManagedCallUseCaseRequest = { name?: string slug?: string enabled?: boolean change_description?: string type?: "managed_call" configuration?: { operation: { method: { ... } path: { ... } headers?: { ... } query_params?: { ... } } request_mapping?: string response_mapping?: string inbound_use_case_slug?: string } type_annotations?: { request?: Record response?: Record } } ``` ### `UpdateSecureProxyUseCaseRequest` ```ts type UpdateSecureProxyUseCaseRequest = { name?: string slug?: string enabled?: boolean change_description?: string type?: "secure_proxy" configuration?: { vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] } } ``` ### `UseCaseHistoryEntry` ```ts type UseCaseHistoryEntry = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } | { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } | { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } // ... } ``` ### `UseCaseHistoryEntryBase` ```ts type UseCaseHistoryEntryBase = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time } ``` ### `InboundUseCaseHistoryEntry` ```ts type InboundUseCaseHistoryEntry = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "inbound" configuration?: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } } ``` ### `OutboundUseCaseHistoryEntry` ```ts type OutboundUseCaseHistoryEntry = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "outbound" configuration?: { event_catalog_event: string event_filter?: string mappings: Array<{ id?: { ... } name: { ... } jsonata_expression?: { ... } enabled: { ... } delivery: { ... } created_at?: { ... } updated_at?: { ... } }> ack_tracking?: "on" | "off" } } ``` ### `FileProxyUseCaseHistoryEntry` ```ts type FileProxyUseCaseHistoryEntry = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "file_proxy" configuration?: { direction?: "download" | "upload" upload?: { max_total_bytes?: { ... } max_file_bytes?: { ... } max_delivery_attempts?: { ... } } fan_out?: { enabled: { ... } } secure_proxy?: { use_case_slug: { ... } } auth?: { type: { ... } token_url: { ... } client_id: { ... } client_secret: { ... } scope?: { ... } audience?: { ... } resource?: { ... } username?: { ... } password?: { ... } body_params?: { ... } headers?: { ... } query_params?: { ... } } params?: Array<{ name: { ... } required: { ... } description?: { ... } }> allowed_origins?: string // uri[] steps: Array<{ url: { ... } method: { ... } headers?: { ... } body_jsonata?: { ... } enabled?: { ... } body?: { ... } response_type: { ... } }> response?: { body: { ... } encoding: { ... } filename?: { ... } content_type?: { ... } } prevent_indirect_serving?: boolean } } ``` ### `ManagedCallUseCaseHistoryEntry` ```ts type ManagedCallUseCaseHistoryEntry = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "managed_call" configuration?: { operation: { method: { ... } path: { ... } headers?: { ... } query_params?: { ... } } request_mapping?: string response_mapping?: string inbound_use_case_slug?: string } type_annotations?: { request?: Record response?: Record } types_locked?: boolean } ``` ### `SecureProxyUseCaseHistoryEntry` ```ts type SecureProxyUseCaseHistoryEntry = { id: string // uuid useCaseId: string // uuid integrationId: string // uuid name: string slug?: string enabled: boolean change_description?: string changed_by?: string created_at: string // date-time updated_at: string // date-time history_created_at: string // date-time type: "secure_proxy" configuration?: { vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] } } ``` ### `SecureProxyUseCaseConfiguration` Configuration for secure_proxy use cases. Defines how to route requests through a secure VPC. ```ts type SecureProxyUseCaseConfiguration = { vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] } ``` ### `SecureProxyWhitelist` Current whitelist state for a secure_proxy use case. vpc_mode is read-only context so the UI can show the user what mode the pool is in. ```ts type SecureProxyWhitelist = { vpc_mode: "static_ip" | "secure_link" allowed_domains: string[] allowed_ips: string[] } ``` ### `SecureProxyWhitelistUpdate` Partial update for a secure_proxy whitelist. At least one of `allowed_domains` or `allowed_ips` must be provided. Per-field semantics: - **omitted** — the field is not modified; the stored value is preserved. - **non-empty array** — the stored value is replaced with the supplied list. - **emp ```ts type SecureProxyWhitelistUpdate = { allowed_domains?: string[] allowed_ips?: string[] } ``` ### `SecureProxySummary` ```ts type SecureProxySummary = { id: string // uuid name: string slug?: string enabled: boolean vpc_mode: "static_ip" | "secure_link" allowed_domains?: string[] allowed_ips?: string[] integration_id: string // uuid integration_name: string } ``` ### `SecureProxyRequest` ```ts type SecureProxyRequest = { integration_id: string // uuid use_case_id?: string // uuid use_case_slug?: string url: string // uri method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" headers?: Record body?: unknown response_type?: "json" | "binary" } ``` ### `SecureProxyResponse` ```ts type SecureProxyResponse = { status_code?: number headers?: Record body?: unknown } ``` ### `SecureProxyUpstreamError` Error payload returned when epilot could not obtain an HTTP response from the proxied target. The failure is epilot-generated (HTTP 502) but the cause is usually remote-side; `code`/`reason` make that attributable. ```ts type SecureProxyUpstreamError = { message: "Upstream network error" | "Upstream error" code?: string reason?: string } ``` ### `ManagedCallOperationConfig` Configuration for managed_call use cases. Defines a single API operation with JSONata mapping. ```ts type ManagedCallOperationConfig = { operation: { method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" path: string headers?: Record query_params?: Record } request_mapping?: string response_mapping?: string inbound_use_case_slug?: string } ``` ### `ManagedCallOperation` HTTP operation configuration for managed calls ```ts type ManagedCallOperation = { method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" path: string headers?: Record query_params?: Record } ``` ### `ManagedCallExecuteRequest` ```ts type ManagedCallExecuteRequest = { integration_id: string // uuid payload?: Record correlation_id?: string } ``` ### `ManagedCallExecuteResponse` The response from a managed call execution. On success, returns the JSONata-mapped response data directly (no wrapper). The shape is entirely defined by your response_mapping JSONata expression. If no response_mapping is configured, returns the raw external API response. Check the X-Inbound-Event-Id ```ts type ManagedCallExecuteResponse = unknown ``` ### `ManagedCallErrorResponse` ```ts type ManagedCallErrorResponse = { error: { code: string message: string details?: Record } } ``` ### `TypeAnnotations` Developer-provided type annotations for a use case's request and response fields ```ts type TypeAnnotations = { request?: Record response?: Record } ``` ### `TypeDescriptor` Describes the inferred type shape of a JSONata expression ```ts type TypeDescriptor = { kind: "object" | "array" | "string" | "number" | "boolean" | "null" | "unknown" | "union" properties?: Record items?: { ... } source?: string variants?: { ... }[] } ``` ### `UseCaseTypePreview` Scaffolded type descriptors for a single use case ```ts type UseCaseTypePreview = { slug: string name?: string request_shape: { kind: "object" | "array" | "string" | "number" | "boolean" | "null" | "unknown" | "union" properties?: Record items?: { ... } source?: string variants?: { ... }[] } response_shape: { kind: "object" | "array" | "string" | "number" | "boolean" | "null" | "unknown" | "union" properties?: Record items?: { ... } source?: string variants?: { ... }[] } existing_annotations?: { request?: Record response?: Record } } ``` ### `GenerateTypesPreviewResponse` ```ts type GenerateTypesPreviewResponse = { integration_name?: string use_cases: Array<{ slug: string name?: string request_shape: { kind: { ... } properties?: { ... } items?: { ... } source?: { ... } variants?: { ... } } response_shape: { kind: { ... } properties?: { ... } items?: { ... } source?: { ... } variants?: { ... } } existing_annotations?: { request?: { ... } response?: { ... } } }> previous_version?: string suggested_version?: string suggested_bump?: "major" | "minor" detected_changes?: Array<{ slug: string field: string type: "breaking" | "non-breaking" description: string }> } ``` ### `GenerateTypesRequest` ```ts type GenerateTypesRequest = { package_name: string version: string description?: string domain_package?: string domain_map_name?: string annotations?: Record response?: Record }> } ``` ### `GenerateTypesResponse` ```ts type GenerateTypesResponse = { package_name: string version: string files: Record warnings?: string[] } ``` ### `CommitTypesRequest` ```ts type CommitTypesRequest = { package_name: string version: string annotations?: Record response?: Record }> } ``` ### `CommitTypesResponse` ```ts type CommitTypesResponse = { committed: boolean warnings?: string[] } ``` ### `FileProxyUseCaseConfiguration` Configuration for file_proxy use cases. Defines how to authenticate and move files between epilot and an external document system, in either direction (see `direction`). **Download** (`direction: download`, the default) fetches a file from the external system and serves it to a browser. The downloa ```ts type FileProxyUseCaseConfiguration = { direction?: "download" | "upload" upload?: { max_total_bytes?: number max_file_bytes?: number max_delivery_attempts?: number } fan_out?: { enabled: boolean } secure_proxy?: { use_case_slug: string } auth?: { type: "oauth2_client_credentials" | "oauth2_password" token_url: string client_id: string client_secret: string scope?: string audience?: string resource?: string username?: string password?: string body_params?: Record headers?: Record query_params?: Record } params?: Array<{ name: string required: boolean description?: string }> allowed_origins?: string // uri[] steps: Array<{ url: string method: "GET" | "POST" | "PUT" | "PATCH" headers?: Record body_jsonata?: string enabled?: string body?: string response_type: "json" | "binary" }> response?: { body: string encoding: "base64" | "binary" filename?: string content_type?: string } prevent_indirect_serving?: boolean } ``` ### `FileProxySecureProxyAttachment` ```ts type FileProxySecureProxyAttachment = { use_case_slug: string } ``` ### `FileProxyAuth` ```ts type FileProxyAuth = { type: "oauth2_client_credentials" | "oauth2_password" token_url: string client_id: string client_secret: string scope?: string audience?: string resource?: string username?: string password?: string body_params?: Record headers?: Record query_params?: Record } ``` ### `FileProxyParam` ```ts type FileProxyParam = { name: string required: boolean description?: string } ``` ### `FileProxyStep` ```ts type FileProxyStep = { url: string method: "GET" | "POST" | "PUT" | "PATCH" headers?: Record body_jsonata?: string enabled?: string body?: string response_type: "json" | "binary" } ``` ### `FileProxyFanOutConfig` Whether one event produces one delivery per file, or a single delivery carrying all of them. The split is always over the event's `event_attachments` — there is no expression to write, because an upload only ever runs on events that declare that field. Each resulting delivery is fully independent: ```ts type FileProxyFanOutConfig = { enabled: boolean } ``` ### `FileProxyUploadConfig` Upload-side settings for a file_proxy use case with `direction: upload`. The surrounding file_proxy configuration owns WHAT and HOW to send: `fan_out`, auth, and the steps with their `body_jsonata`. This nested object governs upload-specific limits and how the final external response is judged. The ```ts type FileProxyUploadConfig = { max_total_bytes?: number max_file_bytes?: number max_delivery_attempts?: number } ``` ### `FileProxyResponseConfig` How to extract the file from the step results. REQUIRED when `direction` is `download`; rejected when `direction` is `upload` (an upload has no file to extract). ```ts type FileProxyResponseConfig = { body: string encoding: "base64" | "binary" filename?: string content_type?: string } ``` ### `MappingSimulationRequest` ```ts type MappingSimulationRequest = { mapping_configuration: { version?: "1.0" mapping: { objects: { ... } } } | { version: "2.0" mapping: { events: { ... } } } object_type: string format: "json" | "xml" payload: string | Record } ``` ### `MappingSimulationV2Request` Request for v2 mapping simulation. Uses the same configuration format stored in integration use case resources, making it easier to test configurations before saving them. ```ts type MappingSimulationV2Request = { event_configuration: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } format: "json" | "xml" payload: string | Record } ``` ### `MappingSimulationResponse` ```ts type MappingSimulationResponse = { entity_updates: Array<{ entity_slug: string unique_identifiers: Record attributes: Record pricing?: { config: { ... } data: { ... } } sharing?: Record mode: "upsert" | "delete" | "purge" }> meter_readings_updates?: Array<{ meter: { $entity_unique_ids: { ... } } meter_counter?: { $entity_unique_ids?: { ... } } attributes: Record mode: "upsert" | "delete" }> prune_scope_updates?: Array<{ entity_slug: string scope: { scope_mode: { ... } schema?: { ... } unique_ids?: { ... } query?: { ... } } keep_unique_ids: Record[] deletion_mode: "delete" | "purge" }> meter_readings_prune_scope_updates?: Array<{ meter: { $entity_unique_ids: { ... } } meter_counter?: { $entity_unique_ids?: { ... } } keep_external_ids: string[] source?: string }> warnings?: Array<{ entity_schema: string field: string message: string }> } ``` ### `MappingSimulationWarning` ```ts type MappingSimulationWarning = { entity_schema: string field: string message: string } ``` ### `DirectPayload` The payload of an ERP event routed to a `direct: true` use case: a versioned envelope of pre-mapped operations that skip the mapping engine. Sent as the `payload` of an `ErpEventV3` - either as a JSON object or as a JSON string (`format` must be `json`; XML is rejected for direct use cases). The sc ```ts type DirectPayload = { version: string operations: Array<{ type?: "entity" entity_slug: string unique_ids: Record unique_id_types?: Record mode?: "upsert" | "delete" | "purge" attributes?: Record } | { type: "meter_reading" meter: { unique_ids: { ... } } counter?: { unique_ids: { ... } } mode?: "upsert" | "delete" reading_matching?: "external_id" | "strict-date" attributes: { external_id: { ... } timestamp: { ... } source: { ... } value: { ... } } }> } ``` ### `DirectEntityOperation` A single pre-mapped entity operation: upserts, soft-deletes, or purges one entity, identified by its unique ids. Produces the same internal update as a mapped-mode entity configuration, so create-vs-update resolution, relation resolution, ordering, and monitoring behave identically. ```ts type DirectEntityOperation = { type?: "entity" entity_slug: string unique_ids: Record unique_id_types?: Record mode?: "upsert" | "delete" | "purge" attributes?: Record | { _set?: { ... } _append?: { ... } _append_all?: { ... } } } | { $relation_ref: Array<{ schema: { ... } unique_ids: { ... } unique_id_types?: { ... } path: { ... } value: { ... } }> | { _set?: { ... } _append?: { ... } _append_all?: { ... } } } | unknown> } ``` ### `DirectMeterReadingOperation` A single pre-mapped meter reading operation: upserts or deletes one reading on a meter (and optionally a specific counter), identified by their unique ids. Produces the same internal update as a mapped-mode meter reading configuration. ```ts type DirectMeterReadingOperation = { type: "meter_reading" meter: { unique_ids: Record } counter?: { unique_ids: Record } mode?: "upsert" | "delete" reading_matching?: "external_id" | "strict-date" attributes: { external_id: string | number timestamp: string source: "ECP" | "ERP" | "360" | "journey-submission" value: number | string } } ``` ### `DirectRelationValue` An entity attribute value that establishes relations to other entities. Written on any attribute inside a direct entity operation's `attributes`. Two forms are accepted: a bare array of items (shorthand for `_set`, i.e. replace), or an object with EXACTLY ONE of the operations `_set` (replace), `_a ```ts type DirectRelationValue = { $relation: Array<{ entity_id?: string schema?: string unique_ids?: Record unique_id_types?: Record tags?: string[] }> | { _set?: Array<{ entity_id?: { ... } schema?: { ... } unique_ids?: { ... } unique_id_types?: { ... } tags?: { ... } }> _append?: Array<{ entity_id?: { ... } schema?: { ... } unique_ids?: { ... } unique_id_types?: { ... } tags?: { ... } }> _append_all?: Array<{ entity_id?: { ... } schema?: { ... } unique_ids?: { ... } unique_id_types?: { ... } tags?: { ... } }> } } ``` ### `DirectRelationItem` One relation target: either an already-resolved reference (`entity_id`), or a lookup by unique ids (`schema` + `unique_ids`, resolved by the pipeline like any other unique-id lookup, including stub creation and retry when the target does not exist yet). The two forms are mutually exclusive. Use `_id ```ts type DirectRelationItem = { entity_id?: string schema?: string unique_ids?: Record unique_id_types?: Record tags?: string[] } ``` ### `DirectRelationRefValue` An entity attribute value that references an ITEM INSIDE a repeatable attribute of another entity - for example one address out of a contact's `address` list. The target entity is looked up by unique ids, then the item at `path` matching `value` is referenced (creating it when missing). The same op ```ts type DirectRelationRefValue = { $relation_ref: Array<{ schema: string unique_ids: Record unique_id_types?: Record path: string value: unknown }> | { _set?: Array<{ schema: { ... } unique_ids: { ... } unique_id_types?: { ... } path: { ... } value: { ... } }> _append?: Array<{ schema: { ... } unique_ids: { ... } unique_id_types?: { ... } path: { ... } value: { ... } }> _append_all?: Array<{ schema: { ... } unique_ids: { ... } unique_id_types?: { ... } path: { ... } value: { ... } }> } } ``` ### `DirectRelationRefItem` One relation-ref target - the entity to look up, and the repeatable item to reference on it. ```ts type DirectRelationRefItem = { schema: string unique_ids: Record unique_id_types?: Record path: string value: unknown } ``` ### `DirectSimulationRequest` Request for a direct-mode dry run: the `direct: true` use case configuration to test against, and the payload to validate and translate. ```ts type DirectSimulationRequest = { event_configuration: { direct?: boolean interactive?: "disabled" | "on_request" | "always" entities?: Array<{ entity_schema: { ... } unique_ids: { ... } jsonataExpression?: { ... } enabled?: { ... } mode?: { ... } scope?: { ... } fields?: { ... } conditional?: { ... } sharing?: { ... } }> meter_readings?: Array<{ jsonataExpression?: { ... } reading_matching?: { ... } mode?: { ... } scope?: { ... } meter: { ... } meter_counter?: { ... } fields: { ... } }> } payload: string | { version: string operations: Array<{ type?: { ... } entity_slug: { ... } unique_ids: { ... } unique_id_types?: { ... } mode?: { ... } attributes?: { ... } } | { type: { ... } meter: { ... } counter?: { ... } mode?: { ... } reading_matching?: { ... } attributes: { ... } }> } } ``` ### `DirectSimulationResponse` Result of a direct-mode dry run. `valid: false` responses list EVERY violation found across all operations in `errors`. `valid: true` responses preview the internal updates the pipeline would apply, plus non-blocking `warnings`. ```ts type DirectSimulationResponse = { valid: boolean errors: Array<{ code: "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DIRECT_ENTITY_NOT_ALLOWED" message: string operation_index?: number }> warnings?: Array<{ entity_schema: string field: string message: string }> entity_updates?: Array<{ entity_slug: string unique_identifiers: Record attributes: Record pricing?: { config: { ... } data: { ... } } sharing?: Record mode: "upsert" | "delete" | "purge" unique_identifiers_metadata?: Record }> meter_reading_updates?: Array<{ meter: { $entity_unique_ids: { ... } } meter_counter?: { $entity_unique_ids?: { ... } } attributes: Record mode: "upsert" | "delete" _config?: { reading_matching?: { ... } } }> } ``` ### `DirectSimulationError` One validation error found during a direct-mode dry run. ```ts type DirectSimulationError = { code: "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DIRECT_ENTITY_NOT_ALLOWED" message: string operation_index?: number } ``` ### `EntityUpdate` ```ts type EntityUpdate = { entity_slug: string unique_identifiers: Record attributes: Record pricing?: { config: Record data: Record[] } sharing?: Record mode: "upsert" | "delete" | "purge" } ``` ### `MeterReadingUpdate` ```ts type MeterReadingUpdate = { meter: { $entity_unique_ids: Record } meter_counter?: { $entity_unique_ids?: Record } attributes: Record mode: "upsert" | "delete" } ``` ### `EntityPruneScopeUpdate` A resolved entity prune scope. At runtime, entities of `entity_slug` found within `scope` whose unique identifiers are not listed in `keep_unique_ids` are removed using `deletion_mode`. ```ts type EntityPruneScopeUpdate = { entity_slug: string scope: { scope_mode: "relations" | "query" schema?: string unique_ids?: Record query?: Record } keep_unique_ids: Record[] deletion_mode: "delete" | "purge" } ``` ### `MeterReadingPruneScopeUpdate` A resolved meter reading prune scope. At runtime, readings of the given meter (+ counter) whose external ids are not listed in `keep_external_ids` are deleted. ```ts type MeterReadingPruneScopeUpdate = { meter: { $entity_unique_ids: Record } meter_counter?: { $entity_unique_ids?: Record } keep_external_ids: string[] source?: string } ``` ### `IntegrationConfigurationV1` ```ts type IntegrationConfigurationV1 = { version?: "1.0" mapping: { objects: Record } } ``` ### `IntegrationObjectV1` ```ts type IntegrationObjectV1 = { unique_ids: Record> fields: Array<{ entity: string attribute: string field?: string jsonataExpression?: string }> } ``` ### `IntegrationFieldV1` ```ts type IntegrationFieldV1 = { entity: string attribute: string field?: string jsonataExpression?: string } ``` ### `IntegrationConfigurationV2` ```ts type IntegrationConfigurationV2 = { version: "2.0" mapping: { events: Record } } ``` ### `OutboundMapping` A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (the raw event payload, or its JSONata transformation when the mapping carries one), or handed to a file_proxy ```ts type OutboundMapping = { id?: string // uuid name: string jsonata_expression?: string enabled: boolean delivery: { type: "webhook" webhook_id: string webhook_name?: string webhook_url?: string } | { type: "poll" retention_days?: number poison_policy?: "dead_letter" | "block" max_delivery_attempts?: number } | { type: "file_proxy" use_case_slug: string } created_at?: string // date-time updated_at?: string // date-time } ``` ### `DeliveryConfig` Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload, or its JSONata transformation when the mapping carries a jsonata_express ```ts type DeliveryConfig = { type: "webhook" webhook_id: string webhook_name?: string webhook_url?: string } | { type: "poll" retention_days?: number poison_policy?: "dead_letter" | "block" max_delivery_attempts?: number } | { type: "file_proxy" use_case_slug: string } ``` ### `WebhookDeliveryConfig` Push delivery of the transformed event to a webhook via svc-webhooks ```ts type WebhookDeliveryConfig = { type: "webhook" webhook_id: string webhook_name?: string webhook_url?: string } ``` ### `PollDeliveryConfig` Pull-based queue delivery. Consumers fetch and acknowledge items via the poll API. When the mapping carries a `jsonata_expression`, it is evaluated once at enqueue time against the standardized event-catalog event (with `$env`/`$mapValue`/`$mapKey` bindings) and its output — a JSON object — is the d ```ts type PollDeliveryConfig = { type: "poll" retention_days?: number poison_policy?: "dead_letter" | "block" max_delivery_attempts?: number } ``` ### `FileProxyDeliveryConfig` Push delivery to an external document system through a `file_proxy` use case. A pure pointer, deliberately. The outbound use case decides WHEN to deliver — its event name plus `event_filter` — and the referenced `file_proxy` use case decides WHAT and HOW: which items to fan out over (`fan_out`), wh ```ts type FileProxyDeliveryConfig = { type: "file_proxy" use_case_slug: string } ``` ### `EntitySyncStatusResponse` ```ts type EntitySyncStatusResponse = { entity_id: string // uuid sync_states: Array<{ entity_id: string // uuid integration_id: string // uuid entity_slug: string use_case_id?: string last_synced_at?: string // date-time last_changed_at?: string // date-time last_operation?: "create" | "patch" | "delete" | "no-op" last_event_id?: string readings_last_synced_at?: string // date-time readings_last_operation?: "upsert" | "delete" readings_last_event_id?: string }> } ``` ### `EntitySyncState` Inbound sync state of one entity for one integration. Carries two independent groups: the entity-level fields (`last_synced_at`, …) and, on meter/meter_counter entities, the readings-level fields (`readings_last_synced_at`, …). Either group can be present alone — a meter whose readings sync via the ```ts type EntitySyncState = { entity_id: string // uuid integration_id: string // uuid entity_slug: string use_case_id?: string last_synced_at?: string // date-time last_changed_at?: string // date-time last_operation?: "create" | "patch" | "delete" | "no-op" last_event_id?: string readings_last_synced_at?: string // date-time readings_last_operation?: "upsert" | "delete" readings_last_event_id?: string } ``` ### `OutboundStatusResponse` ```ts type OutboundStatusResponse = { useCases: Array<{ useCaseId: string // uuid name: string useCaseEnabled: boolean eventCatalogEvent?: string eventEnabled?: boolean webhooks?: Array<{ webhookId: { ... } webhookName?: { ... } enabled?: { ... } }> status: "ok" | "conflict" | "disabled" conflicts?: Array<{ type: { ... } webhookId?: { ... } message: { ... } }> poll?: { queue_depth: { ... } oldest_unconsumed_age_seconds: { ... } last_poll_at: { ... } last_ack_at: { ... } blocked: { ... } dlq_count: { ... } } file_proxy?: Array<{ mapping_id: { ... } use_case_slug: { ... } resolved: { ... } target_use_case_id?: { ... } target_enabled?: { ... } target_updated_at?: { ... } unresolved_reason?: { ... } }> }> } ``` ### `OutboundUseCaseStatus` ```ts type OutboundUseCaseStatus = { useCaseId: string // uuid name: string useCaseEnabled: boolean eventCatalogEvent?: string eventEnabled?: boolean webhooks?: Array<{ webhookId: string webhookName?: string enabled?: boolean }> status: "ok" | "conflict" | "disabled" conflicts?: Array<{ type: "event_disabled" | "all_webhooks_disabled" | "event_enabled_while_disabled" | "webhook_enabled_while_disabled" | "stream_blocked" | "dlq_items_present" webhookId?: string message: string }> poll?: { queue_depth: number oldest_unconsumed_age_seconds: number last_poll_at: string // date-time last_ack_at: string // date-time blocked: boolean dlq_count: number } file_proxy?: Array<{ mapping_id: string use_case_slug: string resolved: boolean target_use_case_id?: string // uuid target_enabled?: boolean target_updated_at?: string // date-time unresolved_reason?: "not_found" | "wrong_type" | "wrong_direction" | "disabled" }> } ``` ### `OutboundFileProxyTargetStatus` Resolution state of one file_proxy mapping's referenced upload use case. Because the transport lives on a separate use case, edits to the endpoint or credentials do not appear in THIS use case's history. `target_updated_at` is the hook that lets an operator notice a target changed underneath a deli ```ts type OutboundFileProxyTargetStatus = { mapping_id: string use_case_slug: string resolved: boolean target_use_case_id?: string // uuid target_enabled?: boolean target_updated_at?: string // date-time unresolved_reason?: "not_found" | "wrong_type" | "wrong_direction" | "disabled" } ``` ### `OutboundPollStatus` Queue/consumer health for a poll-mode use case. Present only on use cases with a poll delivery mapping — webhook-only use cases are unaffected. Depth/age/DLQ numbers are first-page approximations. ```ts type OutboundPollStatus = { queue_depth: number oldest_unconsumed_age_seconds: number last_poll_at: string // date-time last_ack_at: string // date-time blocked: boolean dlq_count: number } ``` ### `WebhookStatus` ```ts type WebhookStatus = { webhookId: string webhookName?: string enabled?: boolean } ``` ### `OutboundConflict` ```ts type OutboundConflict = { type: "event_disabled" | "all_webhooks_disabled" | "event_enabled_while_disabled" | "webhook_enabled_while_disabled" | "stream_blocked" | "dlq_items_present" webhookId?: string message: string } ``` ### `PollOutboundMessagesRequest` ```ts type PollOutboundMessagesRequest = { limit?: number } ``` ### `OutboundMessage` ```ts type OutboundMessage = { id: string lease_token: string use_case_id: string event_name: string event_id: string group: string org_id?: string payload: Record mapping_version?: string enqueued_at: string // date-time } ``` ### `PollOutboundMessagesResponse` ```ts type PollOutboundMessagesResponse = { messages: Array<{ id: string lease_token: string use_case_id: string event_name: string event_id: string group: string org_id?: string payload: Record mapping_version?: string enqueued_at: string // date-time }> visibility_timeout_seconds: number has_more: boolean } ``` ### `AckOutboundMessagesRequest` ```ts type AckOutboundMessagesRequest = { acks: Array<{ id: string lease_token: string }> } ``` ### `AckResult` ```ts type AckResult = { id: string status: "accepted" | "rejected" reason?: "stale_lease" | "out_of_order" | "not_found" } ``` ### `AckOutboundMessagesResponse` ```ts type AckOutboundMessagesResponse = { results: Array<{ id: string status: "accepted" | "rejected" reason?: "stale_lease" | "out_of_order" | "not_found" }> } ``` ### `OutboundDlqMessage` ```ts type OutboundDlqMessage = { id: string use_case_id: string event_name: string event_id: string enqueued_at?: string // date-time dead_lettered_at: string // date-time delivery_attempts: number reason?: string mapping_error?: string mapping_version?: string expires_at?: string // date-time } ``` ### `OutboundDlqListResponse` ```ts type OutboundDlqListResponse = { items: Array<{ id: string use_case_id: string event_name: string event_id: string enqueued_at?: string // date-time dead_lettered_at: string // date-time delivery_attempts: number reason?: string mapping_error?: string mapping_version?: string expires_at?: string // date-time }> next_token?: string } ``` ### `RedriveOutboundDlqRequest` ```ts type RedriveOutboundDlqRequest = { ids: string[] reapply_mapping?: boolean } ``` ### `RedriveOutboundDlqResult` ```ts type RedriveOutboundDlqResult = { id: string status: "redriven" | "not_found" | "mapping_failed" mapping_error?: string } ``` ### `RedriveOutboundDlqResponse` ```ts type RedriveOutboundDlqResponse = { results: Array<{ id: string status: "redriven" | "not_found" | "mapping_failed" mapping_error?: string }> } ``` ### `UnblockOutboundStreamRequest` ```ts type UnblockOutboundStreamRequest = { reason?: string } ``` ### `UnblockOutboundStreamResponse` ```ts type UnblockOutboundStreamResponse = { unblocked: boolean dead_lettered_id?: string } ``` ### `SimulateOutboundMappingRequest` Exactly one of `payload` or `event_id` is required. `event_id` needs `event_catalog_event` to name the event it belongs to. ```ts type SimulateOutboundMappingRequest = { jsonata_expression: string payload?: Record event_id?: string event_catalog_event?: string } ``` ### `OutboundMappingSimulationError` ```ts type OutboundMappingSimulationError = { code: "syntax_error" | "unknown_binding" | "evaluation_error" | "timeout" | "invalid_output" | "expression_too_long" message: string position?: number } ``` ### `SimulateOutboundMappingResponse` ```ts type SimulateOutboundMappingResponse = { valid: boolean output?: Record error?: { code: "syntax_error" | "unknown_binding" | "evaluation_error" | "timeout" | "invalid_output" | "expression_too_long" message: string position?: number } mapping_version: string input?: Record } ``` ### `RelationConfig` ```ts type RelationConfig = { operation: "_set" | "_append" | "_append_all" items?: Array<{ entity_schema: string _tags?: string[] unique_ids: Array<{ attribute: { ... } _type?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } }> required?: boolean }> jsonataExpression?: string } ``` ### `RelationItemConfig` ```ts type RelationItemConfig = { entity_schema: string _tags?: string[] unique_ids: Array<{ attribute: string _type?: "email" | "phone" field?: string jsonataExpression?: string constant?: unknown }> required?: boolean } ``` ### `RelationUniqueIdField` ```ts type RelationUniqueIdField = { attribute: string _type?: "email" | "phone" field?: string jsonataExpression?: string constant?: unknown } ``` ### `RelationRefsConfig` Configuration for relation references ($relation_ref). Relation references link to a specific item within a repeatable attribute on a related entity. Common use case: referencing a specific address within a contact's address list. ```ts type RelationRefsConfig = { operation: "_set" | "_append" | "_append_all" items?: Array<{ entity_schema: string unique_ids: Array<{ attribute: { ... } _type?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } }> path: string value: { attribute: { ... } operation?: { ... } field?: { ... } jsonataExpression?: { ... } constant?: { ... } } }> jsonataExpression?: string } ``` ### `RelationRefItemConfig` Configuration for a single relation reference item ```ts type RelationRefItemConfig = { entity_schema: string unique_ids: Array<{ attribute: string _type?: "email" | "phone" field?: string jsonataExpression?: string constant?: unknown }> path: string value: { attribute: string operation?: "_set" | "_append" | "_append_all" field?: string jsonataExpression?: string constant?: unknown } } ``` ### `RelationRefValueConfig` Configuration for the value to set on the related entity's attribute ```ts type RelationRefValueConfig = { attribute: string operation?: "_set" | "_append" | "_append_all" field?: string jsonataExpression?: string constant?: unknown } ``` ### `RepeatableFieldType` Type hint for repeatable fields that require special search handling. These fields are stored as arrays of objects (e.g., email: []). ```ts type RepeatableFieldType = "email" | "phone" ``` ### `ReplayEventsRequest` ```ts type ReplayEventsRequest = { event_ids: string[] } ``` ### `QueryEventsRequest` ```ts type QueryEventsRequest = { event_id?: string event_type?: "CREATE" | "UPDATE" | "DELETE" correlation_id?: string object_type?: string event_name?: string use_case_id?: string limit?: number cursor?: { event_time?: string // date-time event_id?: string } } ``` ### `QueryInboundMonitoringEventsRequest` ```ts type QueryInboundMonitoringEventsRequest = { use_case_id?: string // uuid event_type?: "CREATE" | "UPDATE" | "DELETE" | "TRIGGER" sync_type?: "entity" | "meter_reading" | "webhook" | "api_deprecation" status?: "success" | "error" | "skipped" | "warning" error_category?: "validation" | "configuration" | "downstream_api" | "timeout" | "system" correlation_id?: string object_type?: string event_name?: string event_id?: string from_date?: string // date-time to_date?: string // date-time limit?: number cursor?: { completed_at?: string // date-time event_id?: string } } ``` ### `QueryAccessLogsRequest` ```ts type QueryAccessLogsRequest = { token_id?: string service?: string method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" path?: string status?: number from_date?: string // date-time to_date?: string // date-time limit?: number cursor?: { timestamp?: string // date-time request_id?: string } } ``` ### `AccessLogEntry` ```ts type AccessLogEntry = { timestamp?: string // date-time environment?: string service?: string request_id?: string method?: string path?: string status?: number response_latency_ms?: number response_length?: number token_id?: string org_id?: string origin?: string source_ip?: string } ``` ### `GetMonitoringStatsRequest` ```ts type GetMonitoringStatsRequest = { from_date?: string // date-time to_date?: string // date-time inbound_group_by?: "use_case_id" | "sync_type" | "status" | "error_category" | "object_type" | "event_name" | "date"[] outbound_group_by?: "event_name" | "status" | "webhook_config_id" | "date"[] } ``` ### `GetMonitoringTimeSeriesRequest` ```ts type GetMonitoringTimeSeriesRequest = { from_date: string // date-time to_date?: string // date-time interval: "5m" | "10m" | "30m" | "1h" | "3h" | "1d" direction?: "inbound" | "outbound" | "both" } ``` ### `TimeSeriesBucket` ```ts type TimeSeriesBucket = { timestamp: string // date-time inbound?: { success_count?: number error_count?: number warning_count?: number skipped_count?: number total_count?: number } outbound?: { success_count?: number error_count?: number pending_count?: number total_count?: number } } ``` ### `QueryOutboundMonitoringEventsRequest` ```ts type QueryOutboundMonitoringEventsRequest = { event_name?: string status?: "succeeded" | "failed" | "pending" webhook_config_id?: string from_date?: string // date-time to_date?: string // date-time limit?: number cursor?: { created_at?: string // date-time event_id?: string } } ``` ### `OutboundMonitoringEvent` ```ts type OutboundMonitoringEvent = { org_id: string event_id: string event_name: string status: "succeeded" | "failed" | "pending" url?: string http_method?: string http_response?: Record webhook_config_id?: string metadata?: Record execution_context?: Record payload?: Record created_at: string // date-time updated_at?: string // date-time } ``` ### `MonitoringStats` ```ts type MonitoringStats = { inbound: { total_events: number total_correlations?: number success_count: number error_count: number skipped_count: number warning_count?: number success_rate?: number last_error_at?: string // date-time breakdown?: Record[] } outbound: { total_events: number success_count: number error_count: number pending_count?: number success_rate?: number last_error_at?: string // date-time breakdown?: Record[] } } ``` ### `InboundMonitoringEvent` ```ts type InboundMonitoringEvent = { org_id: string event_id: string correlation_id?: string integration_id?: string use_case_id?: string event_type?: "CREATE" | "UPDATE" | "DELETE" | "TRIGGER" object_type: string sync_type: "entity" | "meter_reading" | "webhook" | "api_deprecation" status: "success" | "error" | "skipped" | "warning" error_code?: string error_message?: string error_category?: "validation" | "configuration" | "downstream_api" | "timeout" | "system" processing_duration_ms?: number received_at: string // date-time completed_at: string // date-time } ``` ### `QueryMonitoringEventsV2Request` ```ts type QueryMonitoringEventsV2Request = { use_case_id?: string use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" level?: "success" | "error" | "info" | "warning" | "skipped" code?: string event_id?: string correlation_id?: string from_date?: string // date-time to_date?: string // date-time limit?: number cursor?: { created_at?: string // date-time id?: string // uuid } } ``` ### `ExternalMonitoringSpan` A single monitoring span produced by an external system. `correlation_id`, `level`, `use_case_slug`, `occurred_at` and `message` are all required and `level` must be one of success|error|warning|info — but these are validated PER SPAN at ingest and reported in the per-item `results[]`, so one malfor ```ts type ExternalMonitoringSpan = { correlation_id?: string level?: string use_case_slug?: string occurred_at?: string // date-time message?: string detail?: Record } ``` ### `IngestExternalMonitoringEventsRequest` ```ts type IngestExternalMonitoringEventsRequest = { events: Array<{ correlation_id?: string level?: string use_case_slug?: string occurred_at?: string // date-time message?: string detail?: Record }> } ``` ### `IngestExternalMonitoringEventsResponse` ```ts type IngestExternalMonitoringEventsResponse = { accepted: number rejected: number results?: Array<{ index: number status: "accepted" | "rejected" reason?: string }> } ``` ### `MonitoringTraceResponse` ```ts type MonitoringTraceResponse = { correlation_id: string status: "success" | "error" | "warning" | "info" started_at?: string // date-time ended_at?: string // date-time span_count: number truncated: boolean spans: Array<{ id: string // uuid org_id: string integration_id: string event_id: string correlation_id?: string use_case_id?: string use_case_type: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" | "" level: "success" | "error" | "info" | "warning" code?: "ACK_CONFIRMED" | "ACK_PENDING" | "ACK_TIMEOUT" | "ATTACHMENT_NOT_FOUND" | "ATTRIBUTE_TYPE_MISMATCH" | "CONDITIONAL_VARIANTS_WRITTEN" | "CONDITIONAL_VARIANT_WRITE_FAILED" | "CONDITIONAL_VARIANT_WRITE_WARNING" | "CORRELATION_CLOSED_EMPTY" | "CORRELATION_CLOSED_INCOMPLETE" | "CORRELATION_CLOSE_IGNORED" | "CORRELATION_COMPLETED" | "CORRELATION_EVENT_LIMIT_EXCEEDED" | "CORRELATION_ID_MISSING" | "CORRELATION_LATE_EVENT" | "CORRELATION_REQUIREMENT_FAILED" | "CORRELATION_WAIT_REJECTED" | "CORRELATION_WAIT_TIMEOUT" | "DEPRECATED_ENDPOINT" | "DIRECT_ENTITY_NOT_ALLOWED" | "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DUPLICATE_EVENT" | "ENTITY_CREATED" | "ENTITY_DELETED" | "ENTITY_NO_OP" | "ENTITY_REFERENCE_NOT_FOUND" | "ENTITY_UPDATED" | "ENV_VAR_REF_JSONATA_FAILED" | "ENV_VAR_REF_LOOKUP_FAILED" | "ENV_VAR_REF_NOT_FOUND" | "EVENT_NOT_CONFIGURED" | "EXTERNAL_API_ERROR" | "EXTERNAL_ERROR" | "EXTERNAL_INFO" | "EXTERNAL_SUCCESS" | "EXTERNAL_WARNING" | "FAN_OUT_EMPTY" | "FAN_OUT_INVALID_RESULT" | "FILE_EXTRACTION_FAILED" | "FILE_FETCH_FAILED" | "FILE_PROXY_OK" | "FILE_PROXY_UPLOADED" | "FILE_PROXY_UPLOAD_ENQUEUED" | "FILE_PROXY_UPLOAD_FAILED" | "FILE_PROXY_UPLOAD_RETRYING" | "FILE_TOO_LARGE" | "INTEGRATION_NOT_FOUND" | "INTERACTIVE_CROSS_LANE_WRITE" | "INTERACTIVE_NOT_ALLOWED" | "INTERACTIVE_RATE_LIMITED" | "INVALID_METER_READING_ATTRIBUTES" | "LOOKUP_UNMAPPED" | "MALFORMED_PAYLOAD" | "MAPPING_EXPRESSION_FAILED" | "METERING_API_ERROR" | "METER_READING_DELETED" | "METER_READING_GROUP_FAILED" | "METER_READING_GROUP_RETRYING" | "METER_READING_UPSERTED" | "MISSING_METER_COUNTER_UNIQUE_IDS" | "MISSING_METER_UNIQUE_IDS" | "MISSING_REQUIRED_PARAM" | "MISSING_UNIQUE_IDENTIFIERS" | "MSG_ACKED" | "MSG_DEAD_LETTERED" | "MSG_ENQUEUED" | "MSG_EXPIRED_UNPOLLED" | "MSG_HEAD_BLOCKED" | "MSG_LATE_ARRIVAL" | "OAUTH2_TOKEN_FAILURE" | "ORG_DROPPED" | "PAYLOAD_TOO_LARGE" | "PORTAL_REF_AMBIGUOUS" | "PORTAL_REF_JSONATA_FAILED" | "PORTAL_REF_LOOKUP_FAILED" | "PORTAL_REF_NO_MATCH" | "PROCESSING_STATE_LIMIT" | "PRUNE_SCOPE_COMPLETED" | "PRUNE_SCOPE_PARTIAL_FAILURE" | "RECURSION_DEPTH_EXCEEDED" | "RELATION_MISSING_UNIQUE_IDS" | "RELATION_REF_ITEM_NOT_FOUND" | "RELATION_REF_VALUE_UNDEFINED" | "REQUIRED_PARAM_MISSING" | "SECURE_PROXY_DISABLED" | "SECURE_PROXY_DOMAIN_BLOCKED" | "SECURE_PROXY_DOMAIN_NOT_ALLOWED" | "SECURE_PROXY_ERROR" | "SECURE_PROXY_INVALID_CONFIG" | "SECURE_PROXY_INVALID_TYPE" | "SECURE_PROXY_INVALID_URL" | "SECURE_PROXY_IP_BLOCKED" | "SECURE_PROXY_IP_NOT_ALLOWED" | "SECURE_PROXY_NOT_FOUND" | "SECURE_PROXY_OK" | "SECURE_PROXY_UNAVAILABLE" | "SHARING_FAILED" | "SHARING_PARTNER_NOT_CONNECTED" | "SHARING_REJECTED" | "SIGNATURE_VERIFICATION_FAILED" | "SIGNATURE_VERIFICATION_UNAVAILABLE" | "SOFT_DELETED_ENTITY_MATCHED" | "STEP_DISABLED" | "TIMEOUT" | "UNIQUE_ID_LOOKUP_UNRESOLVABLE" | "UNIQUE_ID_MULTIPLE_MATCHES" | "UNIQUE_ID_NOT_IN_SCHEMA" | "UNIQUE_ID_TYPE_DERIVATION_FAILED" | "UNKNOWN_ERROR" | "USE_CASE_DISABLED" | "USE_CASE_INVALID_TYPE" | "USE_CASE_MISSING_CONFIG" | "USE_CASE_NOT_FOUND" | "WEBHOOK_DELIVERED" | "WEBHOOK_DELIVERY_FAILED" | "WEBHOOK_SKIPPED" | string message?: string detail?: Record created_at: string // date-time }> inbound_event?: Record } ``` ### `MonitoringCode` The monitoring code taxonomy — every code the Integration Toolkit itself emits, with a fixed level (see the published code reference at https://docs.epilot.io/docs/integrations/integration-toolkit/monitoring/codes). This schema exists so consumers can import the union as a type. It never constrains ```ts type MonitoringCode = "ACK_CONFIRMED" | "ACK_PENDING" | "ACK_TIMEOUT" | "ATTACHMENT_NOT_FOUND" | "ATTRIBUTE_TYPE_MISMATCH" | "CONDITIONAL_VARIANTS_WRITTEN" | "CONDITIONAL_VARIANT_WRITE_FAILED" | "CONDITIONAL_VARIANT_WRITE_WARNING" | "CORRELATION_CLOSED_EMPTY" | "CORRELATION_CLOSED_INCOMPLETE" | "CORRELATION_CLOSE_IGNORED" | "CORRELATION_COMPLETED" | "CORRELATION_EVENT_LIMIT_EXCEEDED" | "CORRELATION_ID_MISSING" | "CORRELATION_LATE_EVENT" | "CORRELATION_REQUIREMENT_FAILED" | "CORRELATION_WAIT_REJECTED" | "CORRELATION_WAIT_TIMEOUT" | "DEPRECATED_ENDPOINT" | "DIRECT_ENTITY_NOT_ALLOWED" | "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DUPLICATE_EVENT" | "ENTITY_CREATED" | "ENTITY_DELETED" | "ENTITY_NO_OP" | "ENTITY_REFERENCE_NOT_FOUND" | "ENTITY_UPDATED" | "ENV_VAR_REF_JSONATA_FAILED" | "ENV_VAR_REF_LOOKUP_FAILED" | "ENV_VAR_REF_NOT_FOUND" | "EVENT_NOT_CONFIGURED" | "EXTERNAL_API_ERROR" | "EXTERNAL_ERROR" | "EXTERNAL_INFO" | "EXTERNAL_SUCCESS" | "EXTERNAL_WARNING" | "FAN_OUT_EMPTY" | "FAN_OUT_INVALID_RESULT" | "FILE_EXTRACTION_FAILED" | "FILE_FETCH_FAILED" | "FILE_PROXY_OK" | "FILE_PROXY_UPLOADED" | "FILE_PROXY_UPLOAD_ENQUEUED" | "FILE_PROXY_UPLOAD_FAILED" | "FILE_PROXY_UPLOAD_RETRYING" | "FILE_TOO_LARGE" | "INTEGRATION_NOT_FOUND" | "INTERACTIVE_CROSS_LANE_WRITE" | "INTERACTIVE_NOT_ALLOWED" | "INTERACTIVE_RATE_LIMITED" | "INVALID_METER_READING_ATTRIBUTES" | "LOOKUP_UNMAPPED" | "MALFORMED_PAYLOAD" | "MAPPING_EXPRESSION_FAILED" | "METERING_API_ERROR" | "METER_READING_DELETED" | "METER_READING_GROUP_FAILED" | "METER_READING_GROUP_RETRYING" | "METER_READING_UPSERTED" | "MISSING_METER_COUNTER_UNIQUE_IDS" | "MISSING_METER_UNIQUE_IDS" | "MISSING_REQUIRED_PARAM" | "MISSING_UNIQUE_IDENTIFIERS" | "MSG_ACKED" | "MSG_DEAD_LETTERED" | "MSG_ENQUEUED" | "MSG_EXPIRED_UNPOLLED" | "MSG_HEAD_BLOCKED" | "MSG_LATE_ARRIVAL" | "OAUTH2_TOKEN_FAILURE" | "ORG_DROPPED" | "PAYLOAD_TOO_LARGE" | "PORTAL_REF_AMBIGUOUS" | "PORTAL_REF_JSONATA_FAILED" | "PORTAL_REF_LOOKUP_FAILED" | "PORTAL_REF_NO_MATCH" | "PROCESSING_STATE_LIMIT" | "PRUNE_SCOPE_COMPLETED" | "PRUNE_SCOPE_PARTIAL_FAILURE" | "RECURSION_DEPTH_EXCEEDED" | "RELATION_MISSING_UNIQUE_IDS" | "RELATION_REF_ITEM_NOT_FOUND" | "RELATION_REF_VALUE_UNDEFINED" | "REQUIRED_PARAM_MISSING" | "SECURE_PROXY_DISABLED" | "SECURE_PROXY_DOMAIN_BLOCKED" | "SECURE_PROXY_DOMAIN_NOT_ALLOWED" | "SECURE_PROXY_ERROR" | "SECURE_PROXY_INVALID_CONFIG" | "SECURE_PROXY_INVALID_TYPE" | "SECURE_PROXY_INVALID_URL" | "SECURE_PROXY_IP_BLOCKED" | "SECURE_PROXY_IP_NOT_ALLOWED" | "SECURE_PROXY_NOT_FOUND" | "SECURE_PROXY_OK" | "SECURE_PROXY_UNAVAILABLE" | "SHARING_FAILED" | "SHARING_PARTNER_NOT_CONNECTED" | "SHARING_REJECTED" | "SIGNATURE_VERIFICATION_FAILED" | "SIGNATURE_VERIFICATION_UNAVAILABLE" | "SOFT_DELETED_ENTITY_MATCHED" | "STEP_DISABLED" | "TIMEOUT" | "UNIQUE_ID_LOOKUP_UNRESOLVABLE" | "UNIQUE_ID_MULTIPLE_MATCHES" | "UNIQUE_ID_NOT_IN_SCHEMA" | "UNIQUE_ID_TYPE_DERIVATION_FAILED" | "UNKNOWN_ERROR" | "USE_CASE_DISABLED" | "USE_CASE_INVALID_TYPE" | "USE_CASE_MISSING_CONFIG" | "USE_CASE_NOT_FOUND" | "WEBHOOK_DELIVERED" | "WEBHOOK_DELIVERY_FAILED" | "WEBHOOK_SKIPPED" ``` ### `MonitoringEventV2` ```ts type MonitoringEventV2 = { id: string // uuid org_id: string integration_id: string event_id: string correlation_id?: string use_case_id?: string use_case_type: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" | "" level: "success" | "error" | "info" | "warning" code?: "ACK_CONFIRMED" | "ACK_PENDING" | "ACK_TIMEOUT" | "ATTACHMENT_NOT_FOUND" | "ATTRIBUTE_TYPE_MISMATCH" | "CONDITIONAL_VARIANTS_WRITTEN" | "CONDITIONAL_VARIANT_WRITE_FAILED" | "CONDITIONAL_VARIANT_WRITE_WARNING" | "CORRELATION_CLOSED_EMPTY" | "CORRELATION_CLOSED_INCOMPLETE" | "CORRELATION_CLOSE_IGNORED" | "CORRELATION_COMPLETED" | "CORRELATION_EVENT_LIMIT_EXCEEDED" | "CORRELATION_ID_MISSING" | "CORRELATION_LATE_EVENT" | "CORRELATION_REQUIREMENT_FAILED" | "CORRELATION_WAIT_REJECTED" | "CORRELATION_WAIT_TIMEOUT" | "DEPRECATED_ENDPOINT" | "DIRECT_ENTITY_NOT_ALLOWED" | "DIRECT_PAYLOAD_INVALID" | "DIRECT_VERSION_UNSUPPORTED" | "DUPLICATE_EVENT" | "ENTITY_CREATED" | "ENTITY_DELETED" | "ENTITY_NO_OP" | "ENTITY_REFERENCE_NOT_FOUND" | "ENTITY_UPDATED" | "ENV_VAR_REF_JSONATA_FAILED" | "ENV_VAR_REF_LOOKUP_FAILED" | "ENV_VAR_REF_NOT_FOUND" | "EVENT_NOT_CONFIGURED" | "EXTERNAL_API_ERROR" | "EXTERNAL_ERROR" | "EXTERNAL_INFO" | "EXTERNAL_SUCCESS" | "EXTERNAL_WARNING" | "FAN_OUT_EMPTY" | "FAN_OUT_INVALID_RESULT" | "FILE_EXTRACTION_FAILED" | "FILE_FETCH_FAILED" | "FILE_PROXY_OK" | "FILE_PROXY_UPLOADED" | "FILE_PROXY_UPLOAD_ENQUEUED" | "FILE_PROXY_UPLOAD_FAILED" | "FILE_PROXY_UPLOAD_RETRYING" | "FILE_TOO_LARGE" | "INTEGRATION_NOT_FOUND" | "INTERACTIVE_CROSS_LANE_WRITE" | "INTERACTIVE_NOT_ALLOWED" | "INTERACTIVE_RATE_LIMITED" | "INVALID_METER_READING_ATTRIBUTES" | "LOOKUP_UNMAPPED" | "MALFORMED_PAYLOAD" | "MAPPING_EXPRESSION_FAILED" | "METERING_API_ERROR" | "METER_READING_DELETED" | "METER_READING_GROUP_FAILED" | "METER_READING_GROUP_RETRYING" | "METER_READING_UPSERTED" | "MISSING_METER_COUNTER_UNIQUE_IDS" | "MISSING_METER_UNIQUE_IDS" | "MISSING_REQUIRED_PARAM" | "MISSING_UNIQUE_IDENTIFIERS" | "MSG_ACKED" | "MSG_DEAD_LETTERED" | "MSG_ENQUEUED" | "MSG_EXPIRED_UNPOLLED" | "MSG_HEAD_BLOCKED" | "MSG_LATE_ARRIVAL" | "OAUTH2_TOKEN_FAILURE" | "ORG_DROPPED" | "PAYLOAD_TOO_LARGE" | "PORTAL_REF_AMBIGUOUS" | "PORTAL_REF_JSONATA_FAILED" | "PORTAL_REF_LOOKUP_FAILED" | "PORTAL_REF_NO_MATCH" | "PROCESSING_STATE_LIMIT" | "PRUNE_SCOPE_COMPLETED" | "PRUNE_SCOPE_PARTIAL_FAILURE" | "RECURSION_DEPTH_EXCEEDED" | "RELATION_MISSING_UNIQUE_IDS" | "RELATION_REF_ITEM_NOT_FOUND" | "RELATION_REF_VALUE_UNDEFINED" | "REQUIRED_PARAM_MISSING" | "SECURE_PROXY_DISABLED" | "SECURE_PROXY_DOMAIN_BLOCKED" | "SECURE_PROXY_DOMAIN_NOT_ALLOWED" | "SECURE_PROXY_ERROR" | "SECURE_PROXY_INVALID_CONFIG" | "SECURE_PROXY_INVALID_TYPE" | "SECURE_PROXY_INVALID_URL" | "SECURE_PROXY_IP_BLOCKED" | "SECURE_PROXY_IP_NOT_ALLOWED" | "SECURE_PROXY_NOT_FOUND" | "SECURE_PROXY_OK" | "SECURE_PROXY_UNAVAILABLE" | "SHARING_FAILED" | "SHARING_PARTNER_NOT_CONNECTED" | "SHARING_REJECTED" | "SIGNATURE_VERIFICATION_FAILED" | "SIGNATURE_VERIFICATION_UNAVAILABLE" | "SOFT_DELETED_ENTITY_MATCHED" | "STEP_DISABLED" | "TIMEOUT" | "UNIQUE_ID_LOOKUP_UNRESOLVABLE" | "UNIQUE_ID_MULTIPLE_MATCHES" | "UNIQUE_ID_NOT_IN_SCHEMA" | "UNIQUE_ID_TYPE_DERIVATION_FAILED" | "UNKNOWN_ERROR" | "USE_CASE_DISABLED" | "USE_CASE_INVALID_TYPE" | "USE_CASE_MISSING_CONFIG" | "USE_CASE_NOT_FOUND" | "WEBHOOK_DELIVERED" | "WEBHOOK_DELIVERY_FAILED" | "WEBHOOK_SKIPPED" | string message?: string detail?: Record created_at: string // date-time } ``` ### `GetMonitoringStatsV2Request` ```ts type GetMonitoringStatsV2Request = { from_date?: string // date-time to_date?: string // date-time correlation_id?: string correlation_ids?: string[] use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" use_case_types?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy"[] group_by?: "use_case_id" | "use_case_type" | "level" | "code" | "correlation_id" | "date" source?: "monitoring" | "incoming" } ``` ### `GetMonitoringRunCompletionV2Request` ```ts type GetMonitoringRunCompletionV2Request = { correlation_ids: string[] } ``` ### `MonitoringRunCompletionV2Response` ```ts type MonitoringRunCompletionV2Response = { runs: Array<{ correlation_id: string seen: number in_flight: number retrying: number success: number warning: number error: number info: number entries: { total: { ... } error: { ... } warning: { ... } success: { ... } info: { ... } retry: { ... } } last_activity_at: string // date-time }> } ``` ### `MonitoringRunCompletionV2` Per-event completion of one run. Every count is in EVENTS (distinct `event_id`), never rows: `seen = in_flight + success + warning + error + info`. ```ts type MonitoringRunCompletionV2 = { correlation_id: string seen: number in_flight: number retrying: number success: number warning: number error: number info: number entries: { total: number error: number warning: number success: number info: number retry: number } last_activity_at: string // date-time } ``` ### `MonitoringRunEntriesV2` The run's monitoring rows counted by level — the rows its trace lists, correlation-level rows (wait outcomes, closes) included. Unlike the event counts above, one event can contribute many rows (one per entity written, plus every caveat and retry). Retry markers count under `retry` only, so a failed ```ts type MonitoringRunEntriesV2 = { total: number error: number warning: number success: number info: number retry: number } ``` ### `MonitoringStatsV2` ```ts type MonitoringStatsV2 = { total_events: number success_count: number error_count: number warning_count: number skipped_count: number info_count: number ack_timeout_count?: number success_rate?: number last_error_at?: string // date-time last_event_at?: string // date-time breakdown?: Record[] } ``` ### `GetMonitoringTimeSeriesV2Request` ```ts type GetMonitoringTimeSeriesV2Request = { from_date: string // date-time to_date?: string // date-time interval: "5m" | "10m" | "30m" | "1h" | "3h" | "1d" use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" group_by?: "use_case_type" | "use_case" } ``` ### `TimeSeriesBreakdownItemV2` ```ts type TimeSeriesBreakdownItemV2 = { use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" use_case_id?: string success_count: number error_count: number warning_count: number skipped_count: number info_count: number total_count: number } ``` ### `TimeSeriesBucketV2` ```ts type TimeSeriesBucketV2 = { timestamp: string // date-time success_count?: number error_count?: number warning_count?: number skipped_count?: number info_count?: number total_count: number breakdown?: Array<{ use_case_type?: "inbound" | "outbound" | "file_proxy" | "managed_call" | "secure_proxy" use_case_id?: string success_count: number error_count: number warning_count: number skipped_count: number info_count: number total_count: number }> } ``` ### `DocumentationPageSummary` Documentation page metadata without the markdown content ```ts type DocumentationPageSummary = { id: string integration_id: string // uuid scope: "integration" | "use_case" use_case_id?: string // uuid title: string created_at: string // date-time created_by?: string updated_at: string // date-time updated_by?: string } ``` ### `DocumentationPage` A markdown documentation page of an integration ```ts type DocumentationPage = { id: string integration_id: string // uuid scope: "integration" | "use_case" use_case_id?: string // uuid title: string created_at: string // date-time created_by?: string updated_at: string // date-time updated_by?: string content: string } ``` ### `UpsertDocumentationPageRequest` ```ts type UpsertDocumentationPageRequest = { title: string content: string } ```