@epilot/erp-integration-client 0.9.0 → 0.10.0

package/dist/definition.js

@@ -1 +1 @@
-(()=>{"use strict";var e={390:function(e,t,r){var n=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(t,"__esModule",{value:!0});var s=n(r(466));t.default=s.default},466:e=>{e.exports=JSON.parse('{"openapi":"3.0.3","info":{"title":"","version":""},"paths":{"/v1/erp/tracking/acknowledgement":{"post":{"operationId":"acknowledgeTracking","requestBody":{"content":{"application/json":{}}},"responses":{}}},"/v1/erp/trigger":{"post":{"operationId":"triggerErp","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/erp/updates/events":{"post":{"operationId":"processErpUpdatesEvents","requestBody":{"content":{"application/json":{}}},"responses":{}}},"/v2/erp/updates/events":{"post":{"operationId":"processErpUpdatesEventsV2","requestBody":{"content":{"application/json":{}}},"responses":{}}},"/v1/erp/updates/mapping_simulation":{"post":{"operationId":"simulateMapping","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/integrations":{"get":{"operationId":"listIntegrations","responses":{}},"post":{"operationId":"createIntegration","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/integrations/{integrationId}":{"get":{"operationId":"getIntegration","parameters":[{"name":"integrationId","in":"path","required":true}],"responses":{}},"put":{"operationId":"updateIntegration","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}},"delete":{"operationId":"deleteIntegration","parameters":[{"name":"integrationId","in":"path","required":true}],"responses":{}}},"/v1/integrations/{integrationId}/use-cases":{"get":{"operationId":"listUseCases","parameters":[{"name":"integrationId","in":"path","required":true}],"responses":{}},"post":{"operationId":"createUseCase","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/integrations/{integrationId}/use-cases/{useCaseId}":{"get":{"operationId":"getUseCase","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true}],"responses":{}},"put":{"operationId":"updateUseCase","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}},"delete":{"operationId":"deleteUseCase","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true}],"responses":{}}},"/v1/integrations/{integrationId}/use-cases/{useCaseId}/history":{"get":{"operationId":"listUseCaseHistory","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true},{"name":"cursor","in":"query","required":false}],"responses":{}}},"/v1/integrations/{integrationId}/app-mapping":{"put":{"operationId":"setIntegrationAppMapping","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}},"delete":{"operationId":"deleteIntegrationAppMapping","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}}},"components":{"responses":{"BadRequest":{"content":{"application/json":{}}},"Unauthorized":{"content":{"application/json":{}}},"InternalServerError":{"content":{"application/json":{}}},"ERPUpdatesResponse":{"content":{"application/json":{}}},"TriggerWebhookResponse":{"content":{"application/json":{}}}}},"servers":[{"url":"https://erp-integration-api.sls.epilot.io"}]}')}},t={},r=function r(n){var s=t[n];if(void 0!==s)return s.exports;var a=t[n]={exports:{}};return e[n].call(a.exports,a,a.exports,r),a.exports}(390),n=exports;for(var s in r)n[s]=r[s];r.__esModule&&Object.defineProperty(n,"__esModule",{value:!0})})();
+(()=>{"use strict";var e={330:function(e,t,n){var r=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:e}};Object.defineProperty(t,"__esModule",{value:!0});var s=r(n(466));t.default=s.default},466:e=>{e.exports=JSON.parse('{"openapi":"3.0.3","info":{"title":"","version":""},"paths":{"/v1/erp/tracking/acknowledgement":{"post":{"operationId":"acknowledgeTracking","requestBody":{"content":{"application/json":{}}},"responses":{}}},"/v1/erp/trigger":{"post":{"operationId":"triggerErp","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/erp/updates/events":{"post":{"operationId":"processErpUpdatesEvents","requestBody":{"content":{"application/json":{}}},"responses":{}}},"/v2/erp/updates/events":{"post":{"operationId":"processErpUpdatesEventsV2","requestBody":{"content":{"application/json":{}}},"responses":{}}},"/v2/erp/updates/mapping_simulation":{"post":{"operationId":"simulateMappingV2","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/erp/updates/mapping_simulation":{"post":{"operationId":"simulateMapping","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/integrations":{"get":{"operationId":"listIntegrations","responses":{}},"post":{"operationId":"createIntegration","requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/integrations/{integrationId}":{"get":{"operationId":"getIntegration","parameters":[{"name":"integrationId","in":"path","required":true}],"responses":{}},"put":{"operationId":"updateIntegration","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}},"delete":{"operationId":"deleteIntegration","parameters":[{"name":"integrationId","in":"path","required":true}],"responses":{}}},"/v1/integrations/{integrationId}/use-cases":{"get":{"operationId":"listUseCases","parameters":[{"name":"integrationId","in":"path","required":true}],"responses":{}},"post":{"operationId":"createUseCase","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}},"/v1/integrations/{integrationId}/use-cases/{useCaseId}":{"get":{"operationId":"getUseCase","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true}],"responses":{}},"put":{"operationId":"updateUseCase","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}},"delete":{"operationId":"deleteUseCase","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true}],"responses":{}}},"/v1/integrations/{integrationId}/use-cases/{useCaseId}/history":{"get":{"operationId":"listUseCaseHistory","parameters":[{"name":"integrationId","in":"path","required":true},{"name":"useCaseId","in":"path","required":true},{"name":"cursor","in":"query","required":false}],"responses":{}}},"/v1/integrations/{integrationId}/app-mapping":{"put":{"operationId":"setIntegrationAppMapping","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}},"delete":{"operationId":"deleteIntegrationAppMapping","parameters":[{"name":"integrationId","in":"path","required":true}],"requestBody":{"required":true,"content":{"application/json":{}}},"responses":{}}}},"components":{"responses":{"BadRequest":{"content":{"application/json":{}}},"Unauthorized":{"content":{"application/json":{}}},"InternalServerError":{"content":{"application/json":{}}},"ERPUpdatesResponse":{"content":{"application/json":{}}},"TriggerWebhookResponse":{"content":{"application/json":{}}}}}}')}},t={},n=function n(r){var s=t[r];if(void 0!==s)return s.exports;var a=t[r]={exports:{}};return e[r].call(a.exports,a,a.exports,n),a.exports}(330),r=exports;for(var s in n)r[s]=n[s];n.__esModule&&Object.defineProperty(r,"__esModule",{value:!0})})();

package/dist/openapi-runtime.json

@@ -50,6 +50,18 @@
         "responses": {}
       }
     },
+    "/v2/erp/updates/mapping_simulation": {
+      "post": {
+        "operationId": "simulateMappingV2",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {}
+          }
+        },
+        "responses": {}
+      }
+    },
     "/v1/erp/updates/mapping_simulation": {
       "post": {
         "operationId": "simulateMapping",
@@ -293,10 +305,5 @@
         }
       }
     }
-  },
-  "servers": [
-    {
-      "url": "https://erp-integration-api.sls.epilot.io"
-    }
-  ]
+  }
 }

package/dist/openapi.d.ts

@@ -358,6 +358,13 @@ declare namespace Components {
              */
             enabled?: /* Controls whether this field mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean. Defaults to true if omitted. */ boolean | string;
             relations?: RelationConfig;
+            relation_refs?: /**
+             * 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.
+             *
+             */
+            RelationRefsConfig;
         }
         export interface IntegrationFieldV1 {
             /**
@@ -427,6 +434,24 @@ declare namespace Components {
             entity_updates: EntityUpdate[];
             meter_readings_updates?: MeterReadingUpdate[];
         }
+        /**
+         * 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.
+         *
+         */
+        export interface MappingSimulationV2Request {
+            event_configuration: /* Configuration for inbound use cases (ERP to epilot) */ InboundIntegrationEventConfiguration;
+            /**
+             * Format of the payload data
+             */
+            format: "json" | "xml";
+            /**
+             * The event data payload - can be either a serialized string or a direct JSON object
+             */
+            payload: /* The event data payload - can be either a serialized string or a direct JSON object */ string | {
+                [name: string]: any;
+            };
+        }
         export interface MeterReadingUpdate {
             meter: {
                 /**
@@ -548,10 +573,11 @@ declare namespace Components {
             /**
              * Relation operation:
              * - '_set': Replace all existing relations with the specified items
-             * - '_append': Add new items to existing relations (fetches current entity first)
+             * - '_append': Add new unique items to existing relations (deduplicates by entity_id)
+             * - '_append_all': Add all items to existing relations (no deduplication, allows duplicates)
              *
              */
-            operation: "_set" | "_append";
+            operation: "_set" | "_append" | "_append_all";
             /**
              * Array of relation item configurations
              */
@@ -575,6 +601,77 @@ declare namespace Components {
              */
             unique_ids: RelationUniqueIdField[];
         }
+        /**
+         * Configuration for a single relation reference item
+         */
+        export interface RelationRefItemConfig {
+            /**
+             * Schema of the related entity (e.g., "contact")
+             */
+            entity_schema: string;
+            /**
+             * Unique identifier mappings for the related entity
+             */
+            unique_ids: RelationUniqueIdField[];
+            /**
+             * Attribute path on the related entity (e.g., "address")
+             */
+            path: string;
+            value: /* Configuration for the value to set on the related entity's attribute */ RelationRefValueConfig;
+        }
+        /**
+         * Configuration for the value to set on the related entity's attribute
+         */
+        export interface RelationRefValueConfig {
+            /**
+             * Target attribute name on the related entity
+             */
+            attribute: string;
+            /**
+             * Operation for the attribute value:
+             * - '_set': Replace the attribute value
+             * - '_append': Add new unique items (deduplicates)
+             * - '_append_all': Add all items (no deduplication)
+             *
+             */
+            operation?: "_set" | "_append" | "_append_all";
+            /**
+             * Source field name from the event data
+             */
+            field?: string;
+            /**
+             * JSONata expression to compute the value
+             */
+            jsonataExpression?: string;
+            /**
+             * Constant value (any type)
+             */
+            constant?: any;
+        }
+        /**
+         * 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.
+         *
+         */
+        export interface RelationRefsConfig {
+            /**
+             * Relation reference operation:
+             * - '_set': Replace all existing relation_refs with the specified items
+             * - '_append': Add new unique items to existing relation_refs (deduplicates by entity_id + _id)
+             * - '_append_all': Add all items to existing relation_refs (no deduplication, allows duplicates)
+             *
+             */
+            operation: "_set" | "_append" | "_append_all";
+            /**
+             * Array of relation reference item configurations
+             */
+            items?: /* Configuration for a single relation reference item */ RelationRefItemConfig[];
+            /**
+             * JSONata expression that returns relation_ref items array (alternative to 'items')
+             */
+            jsonataExpression?: string;
+        }
         export interface RelationUniqueIdField {
             /**
              * Target attribute name in the related entity
@@ -1026,6 +1123,21 @@ declare namespace Paths {
             export type $500 = Components.Responses.InternalServerError;
         }
     }
+    namespace SimulateMappingV2 {
+        export type RequestBody = /**
+         * 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.
+         *
+         */
+        Components.Schemas.MappingSimulationV2Request;
+        namespace Responses {
+            export type $200 = Components.Schemas.MappingSimulationResponse;
+            export type $400 = Components.Responses.BadRequest;
+            export type $401 = Components.Responses.Unauthorized;
+            export type $422 = Components.Schemas.ErrorResponseBase;
+            export type $500 = Components.Responses.InternalServerError;
+        }
+    }
     namespace TriggerErp {
         export type RequestBody = Components.Schemas.TriggerErpActionRequest;
         namespace Responses {
@@ -1121,6 +1233,22 @@ export interface OperationMethods {
     data?: Paths.ProcessErpUpdatesEventsV2.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.ProcessErpUpdatesEventsV2.Responses.$200>
+  /**
+   * simulateMappingV2 - simulateMappingV2
+   * 
+   * Test v2.0 mapping configuration by transforming a payload using the provided mapping rules without persisting data.
+   * 
+   * This endpoint accepts the same configuration format that is stored in the integration use case resource,
+   * making it easier to test configurations before saving them to a use case.
+   * 
+   * See documentation at /docs/MAPPING_V2.md for detailed v2.0 format specification.
+   * 
+   */
+  'simulateMappingV2'(
+    parameters?: Parameters<UnknownParamsObject> | null,
+    data?: Paths.SimulateMappingV2.RequestBody,
+    config?: AxiosRequestConfig  
+  ): OperationResponse<Paths.SimulateMappingV2.Responses.$200>
   /**
    * simulateMapping - simulateMapping
    * 
@@ -1326,6 +1454,24 @@ export interface PathsDictionary {
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.ProcessErpUpdatesEventsV2.Responses.$200>
   }
+  ['/v2/erp/updates/mapping_simulation']: {
+    /**
+     * simulateMappingV2 - simulateMappingV2
+     * 
+     * Test v2.0 mapping configuration by transforming a payload using the provided mapping rules without persisting data.
+     * 
+     * This endpoint accepts the same configuration format that is stored in the integration use case resource,
+     * making it easier to test configurations before saving them to a use case.
+     * 
+     * See documentation at /docs/MAPPING_V2.md for detailed v2.0 format specification.
+     * 
+     */
+    'post'(
+      parameters?: Parameters<UnknownParamsObject> | null,
+      data?: Paths.SimulateMappingV2.RequestBody,
+      config?: AxiosRequestConfig  
+    ): OperationResponse<Paths.SimulateMappingV2.Responses.$200>
+  }
   ['/v1/erp/updates/mapping_simulation']: {
     /**
      * simulateMapping - simulateMapping
@@ -1520,6 +1666,7 @@ export type IntegrationMeterReading = Components.Schemas.IntegrationMeterReading
 export type IntegrationObjectV1 = Components.Schemas.IntegrationObjectV1;
 export type MappingSimulationRequest = Components.Schemas.MappingSimulationRequest;
 export type MappingSimulationResponse = Components.Schemas.MappingSimulationResponse;
+export type MappingSimulationV2Request = Components.Schemas.MappingSimulationV2Request;
 export type MeterReadingUpdate = Components.Schemas.MeterReadingUpdate;
 export type MeterUniqueIdsConfig = Components.Schemas.MeterUniqueIdsConfig;
 export type OutboundIntegrationEventConfiguration = Components.Schemas.OutboundIntegrationEventConfiguration;
@@ -1527,6 +1674,9 @@ export type OutboundUseCase = Components.Schemas.OutboundUseCase;
 export type OutboundUseCaseHistoryEntry = Components.Schemas.OutboundUseCaseHistoryEntry;
 export type RelationConfig = Components.Schemas.RelationConfig;
 export type RelationItemConfig = Components.Schemas.RelationItemConfig;
+export type RelationRefItemConfig = Components.Schemas.RelationRefItemConfig;
+export type RelationRefValueConfig = Components.Schemas.RelationRefValueConfig;
+export type RelationRefsConfig = Components.Schemas.RelationRefsConfig;
 export type RelationUniqueIdField = Components.Schemas.RelationUniqueIdField;
 export type SetIntegrationAppMappingRequest = Components.Schemas.SetIntegrationAppMappingRequest;
 export type TriggerErpActionRequest = Components.Schemas.TriggerErpActionRequest;

package/dist/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.13.0",
+    "version": "0.15.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -272,6 +272,277 @@
         }
       }
     },
+    "/v2/erp/updates/mapping_simulation": {
+      "post": {
+        "operationId": "simulateMappingV2",
+        "summary": "simulateMappingV2",
+        "description": "Test v2.0 mapping configuration by transforming a payload using the provided mapping rules without persisting data.\n\nThis endpoint accepts the same configuration format that is stored in the integration use case resource,\nmaking it easier to test configurations before saving them to a use case.\n\nSee documentation at /docs/MAPPING_V2.md for detailed v2.0 format specification.\n",
+        "tags": [
+          "erp"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MappingSimulationV2Request"
+              },
+              "examples": {
+                "simple": {
+                  "summary": "Simple Example",
+                  "value": {
+                    "event_configuration": {
+                      "entities": [
+                        {
+                          "entity_schema": "contact",
+                          "unique_ids": [
+                            "customer_number"
+                          ],
+                          "fields": [
+                            {
+                              "attribute": "customer_number",
+                              "field": "customerId"
+                            },
+                            {
+                              "attribute": "first_name",
+                              "field": "firstName"
+                            },
+                            {
+                              "attribute": "last_name",
+                              "field": "lastName"
+                            },
+                            {
+                              "attribute": "email",
+                              "field": "email"
+                            },
+                            {
+                              "attribute": "source",
+                              "constant": "ERP"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "format": "json",
+                    "payload": "{\"customerId\":\"12345\",\"firstName\":\"Anna\",\"lastName\":\"Schmidt\",\"email\":\"anna@example.com\"}"
+                  }
+                },
+                "advanced_with_relations": {
+                  "summary": "Advanced with Relations",
+                  "value": {
+                    "event_configuration": {
+                      "entities": [
+                        {
+                          "entity_schema": "contract",
+                          "unique_ids": [
+                            "contract_number"
+                          ],
+                          "fields": [
+                            {
+                              "attribute": "contract_number",
+                              "field": "number"
+                            },
+                            {
+                              "attribute": "display_name",
+                              "field": "displayName"
+                            },
+                            {
+                              "attribute": "billing_account",
+                              "relations": {
+                                "operation": "_set",
+                                "items": [
+                                  {
+                                    "entity_schema": "billing_account",
+                                    "_tags": [
+                                      "PRIMARY"
+                                    ],
+                                    "unique_ids": [
+                                      {
+                                        "attribute": "external_id",
+                                        "field": "customerAccountId"
+                                      }
+                                    ]
+                                  }
+                                ]
+                              }
+                            }
+                          ]
+                        },
+                        {
+                          "entity_schema": "meter",
+                          "unique_ids": [
+                            "meter_number"
+                          ],
+                          "jsonataExpression": "meters.{\"number\": number, \"type\": meterType}",
+                          "fields": [
+                            {
+                              "attribute": "meter_number",
+                              "field": "number"
+                            },
+                            {
+                              "attribute": "meter_type",
+                              "field": "type"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "format": "json",
+                    "payload": "{\"number\":\"CTR-001\",\"displayName\":\"Premium Contract\",\"customerAccountId\":\"ACC-999\",\"meters\":[{\"number\":\"M-001\",\"meterType\":\"electricity\"},{\"number\":\"M-002\",\"meterType\":\"gas\"}]}"
+                  }
+                },
+                "with_meter_readings": {
+                  "summary": "With Meter Readings",
+                  "value": {
+                    "event_configuration": {
+                      "entities": [
+                        {
+                          "entity_schema": "contract",
+                          "unique_ids": [
+                            "contract_number"
+                          ],
+                          "fields": [
+                            {
+                              "attribute": "contract_number",
+                              "field": "number"
+                            },
+                            {
+                              "attribute": "display_name",
+                              "field": "name"
+                            }
+                          ]
+                        }
+                      ],
+                      "meter_readings": [
+                        {
+                          "jsonataExpression": "$.readings",
+                          "meter": {
+                            "unique_ids": [
+                              {
+                                "attribute": "external_id",
+                                "field": "meter_id"
+                              }
+                            ]
+                          },
+                          "fields": [
+                            {
+                              "attribute": "external_id",
+                              "field": "reading_id"
+                            },
+                            {
+                              "attribute": "timestamp",
+                              "field": "read_at"
+                            },
+                            {
+                              "attribute": "source",
+                              "constant": "ERP"
+                            },
+                            {
+                              "attribute": "value",
+                              "field": "value"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "format": "json",
+                    "payload": "{\"number\":\"CTR-001\",\"name\":\"Main Contract\",\"readings\":[{\"meter_id\":\"M-001\",\"reading_id\":\"R-001\",\"read_at\":\"2025-01-15T10:00:00Z\",\"value\":12345.6}]}"
+                  }
+                },
+                "conditional_fields": {
+                  "summary": "Conditional Field Processing",
+                  "description": "Example showing how to conditionally enable/disable individual field mappings",
+                  "value": {
+                    "event_configuration": {
+                      "entities": [
+                        {
+                          "entity_schema": "contact",
+                          "unique_ids": [
+                            "customer_number"
+                          ],
+                          "fields": [
+                            {
+                              "attribute": "customer_number",
+                              "field": "customerId"
+                            },
+                            {
+                              "attribute": "email",
+                              "field": "email",
+                              "enabled": "$exists(email) and email != ''"
+                            },
+                            {
+                              "attribute": "phone",
+                              "field": "phone",
+                              "enabled": "$exists(phone) and phone != ''"
+                            },
+                            {
+                              "attribute": "vip_status",
+                              "constant": "VIP",
+                              "enabled": "vipFlag = true"
+                            },
+                            {
+                              "attribute": "billing_account",
+                              "enabled": "$exists(billingAccountId)",
+                              "relations": {
+                                "operation": "_set",
+                                "items": [
+                                  {
+                                    "entity_schema": "billing_account",
+                                    "unique_ids": [
+                                      {
+                                        "attribute": "external_id",
+                                        "field": "billingAccountId"
+                                      }
+                                    ]
+                                  }
+                                ]
+                              }
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    "format": "json",
+                    "payload": "{\"customerId\":\"12345\",\"email\":\"user@example.com\",\"phone\":\"\",\"vipFlag\":true,\"billingAccountId\":\"ACC-999\"}"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successfully simulated mapping",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MappingSimulationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "422": {
+            "description": "Unprocessable entity - mapping configuration or payload validation failed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/erp/updates/mapping_simulation": {
       "post": {
         "operationId": "simulateMapping",
@@ -2111,6 +2382,43 @@
           }
         }
       },
+      "MappingSimulationV2Request": {
+        "type": "object",
+        "description": "Request for v2 mapping simulation. Uses the same configuration format stored in integration use case resources,\nmaking it easier to test configurations before saving them.\n",
+        "required": [
+          "event_configuration",
+          "format",
+          "payload"
+        ],
+        "properties": {
+          "event_configuration": {
+            "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "json",
+              "xml"
+            ],
+            "default": "json",
+            "description": "Format of the payload data"
+          },
+          "payload": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "The serialized event data payload (JSON, XML, etc.) as a string"
+              },
+              {
+                "type": "object",
+                "description": "Direct JSON object (will be automatically serialized)",
+                "additionalProperties": true
+              }
+            ],
+            "description": "The event data payload - can be either a serialized string or a direct JSON object"
+          }
+        }
+      },
       "MappingSimulationResponse": {
         "type": "object",
         "required": [
@@ -2462,6 +2770,9 @@
           },
           "relations": {
             "$ref": "#/components/schemas/RelationConfig"
+          },
+          "relation_refs": {
+            "$ref": "#/components/schemas/RelationRefsConfig"
           }
         }
       },
@@ -2475,9 +2786,10 @@
             "type": "string",
             "enum": [
               "_set",
-              "_append"
+              "_append",
+              "_append_all"
             ],
-            "description": "Relation operation:\n- '_set': Replace all existing relations with the specified items\n- '_append': Add new items to existing relations (fetches current entity first)\n"
+            "description": "Relation operation:\n- '_set': Replace all existing relations with the specified items\n- '_append': Add new unique items to existing relations (deduplicates by entity_id)\n- '_append_all': Add all items to existing relations (no deduplication, allows duplicates)\n"
           },
           "items": {
             "type": "array",
@@ -2541,6 +2853,98 @@
             "description": "Constant value (any type)"
           }
         }
+      },
+      "RelationRefsConfig": {
+        "type": "object",
+        "description": "Configuration for relation references ($relation_ref).\nRelation references link to a specific item within a repeatable attribute on a related entity.\nCommon use case: referencing a specific address within a contact's address list.\n",
+        "required": [
+          "operation"
+        ],
+        "properties": {
+          "operation": {
+            "type": "string",
+            "enum": [
+              "_set",
+              "_append",
+              "_append_all"
+            ],
+            "description": "Relation reference operation:\n- '_set': Replace all existing relation_refs with the specified items\n- '_append': Add new unique items to existing relation_refs (deduplicates by entity_id + _id)\n- '_append_all': Add all items to existing relation_refs (no deduplication, allows duplicates)\n"
+          },
+          "items": {
+            "type": "array",
+            "description": "Array of relation reference item configurations",
+            "items": {
+              "$ref": "#/components/schemas/RelationRefItemConfig"
+            }
+          },
+          "jsonataExpression": {
+            "type": "string",
+            "description": "JSONata expression that returns relation_ref items array (alternative to 'items')"
+          }
+        }
+      },
+      "RelationRefItemConfig": {
+        "type": "object",
+        "description": "Configuration for a single relation reference item",
+        "required": [
+          "entity_schema",
+          "unique_ids",
+          "path",
+          "value"
+        ],
+        "properties": {
+          "entity_schema": {
+            "type": "string",
+            "description": "Schema of the related entity (e.g., \"contact\")"
+          },
+          "unique_ids": {
+            "type": "array",
+            "description": "Unique identifier mappings for the related entity",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
+          },
+          "path": {
+            "type": "string",
+            "description": "Attribute path on the related entity (e.g., \"address\")"
+          },
+          "value": {
+            "$ref": "#/components/schemas/RelationRefValueConfig"
+          }
+        }
+      },
+      "RelationRefValueConfig": {
+        "type": "object",
+        "description": "Configuration for the value to set on the related entity's attribute",
+        "required": [
+          "attribute"
+        ],
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "description": "Target attribute name on the related entity"
+          },
+          "operation": {
+            "type": "string",
+            "enum": [
+              "_set",
+              "_append",
+              "_append_all"
+            ],
+            "description": "Operation for the attribute value:\n- '_set': Replace the attribute value\n- '_append': Add new unique items (deduplicates)\n- '_append_all': Add all items (no deduplication)\n"
+          },
+          "field": {
+            "type": "string",
+            "description": "Source field name from the event data"
+          },
+          "jsonataExpression": {
+            "type": "string",
+            "description": "JSONata expression to compute the value"
+          },
+          "constant": {
+            "description": "Constant value (any type)"
+          }
+        }
       }
     },
     "responses": {
@@ -2625,13 +3029,5 @@
         }
       }
     }
-  },
-  "servers": [
-    {
-      "url": "https://erp-integration-api.sls.epilot.io"
-    },
-    {
-      "url": "https://erp-integration-api.sls.epilot.io"
-    }
-  ]
+  }
 }

package/package.json

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