@epilot/cli 0.1.127 → 0.1.128

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.127 — CLI for epilot APIs
+epilot v0.1.128 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/integration-toolkit.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Integration Toolkit API",
-    "version": "1.19.0",
+    "version": "1.21.0",
     "description": "API for integrating with external systems in a standardised way."
   },
   "tags": [
@@ -619,6 +619,167 @@
         }
       }
     },
+    "/v1/erp/updates/direct_simulation": {
+      "post": {
+        "operationId": "simulateDirect",
+        "summary": "simulateDirect",
+        "description": "Dry run for direct-mode payloads: validates a `DirectPayload` against a `direct: true`\nuse case configuration and previews the internal entity and meter reading updates the\npipeline would apply — without persisting anything.\n\nUnlike the ingest endpoint, validation does not stop at the first problem: ALL issues\nacross all operations are collected into `errors`, each carrying the index of the\noperation it refers to. When the payload is valid, the response additionally contains\nthe translated update previews plus non-blocking `warnings` (for example unique-id\nfields that are not defined in the target entity schema, or a failed server-side\nunique-id type derivation).\n\nUse this endpoint while designing a direct integration, before sending events to\n`POST /v3/erp/updates/events`. See documentation at /docs/DIRECT_MODE.md.\n",
+        "tags": [
+          "erp"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DirectSimulationRequest"
+              },
+              "examples": {
+                "entity_upsert": {
+                  "summary": "Entity upsert (open mode)",
+                  "value": {
+                    "event_configuration": {
+                      "direct": true
+                    },
+                    "payload": {
+                      "version": "1",
+                      "operations": [
+                        {
+                          "entity_slug": "contact",
+                          "unique_ids": {
+                            "customer_number": "CUST-12345"
+                          },
+                          "attributes": {
+                            "first_name": "Anna",
+                            "last_name": "Schmidt",
+                            "email": "anna.schmidt@example.com"
+                          }
+                        }
+                      ]
+                    }
+                  }
+                },
+                "allowlist_with_relation": {
+                  "summary": "Allowlisted entities with a relation",
+                  "value": {
+                    "event_configuration": {
+                      "direct": true,
+                      "entities": [
+                        {
+                          "entity_schema": "contract",
+                          "unique_ids": [
+                            "contract_number"
+                          ]
+                        },
+                        {
+                          "entity_schema": "contact",
+                          "unique_ids": [
+                            "customer_number"
+                          ]
+                        }
+                      ]
+                    },
+                    "payload": {
+                      "version": "1",
+                      "operations": [
+                        {
+                          "entity_slug": "contract",
+                          "unique_ids": {
+                            "contract_number": "CTR-001"
+                          },
+                          "attributes": {
+                            "display_name": "Premium Contract",
+                            "customer": {
+                              "$relation": {
+                                "_set": [
+                                  {
+                                    "schema": "contact",
+                                    "unique_ids": {
+                                      "customer_number": "CUST-12345"
+                                    },
+                                    "tags": [
+                                      "primary"
+                                    ]
+                                  }
+                                ]
+                              }
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  }
+                },
+                "meter_reading": {
+                  "summary": "Meter reading",
+                  "value": {
+                    "event_configuration": {
+                      "direct": true
+                    },
+                    "payload": {
+                      "version": "1",
+                      "operations": [
+                        {
+                          "type": "meter_reading",
+                          "meter": {
+                            "unique_ids": {
+                              "meter_number": "M-001"
+                            }
+                          },
+                          "counter": {
+                            "unique_ids": {
+                              "obis_number": "1-0:1.8.0"
+                            }
+                          },
+                          "reading_matching": "strict-date",
+                          "attributes": {
+                            "external_id": "R-001",
+                            "timestamp": "2026-08-24T06:00:00Z",
+                            "source": "ERP",
+                            "value": 12345.6
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Simulation executed - `valid` reports the verdict, `errors` lists every violation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DirectSimulationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "422": {
+            "description": "Unprocessable entity - simulation could not be executed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/erp/updates/mapping_simulation": {
       "post": {
         "operationId": "simulateMapping",
@@ -2844,6 +3005,59 @@
         }
       }
     },
+    "/v1/entities/{entityId}/sync-status": {
+      "get": {
+        "operationId": "getEntitySyncStatus",
+        "summary": "getEntitySyncStatus",
+        "description": "Get the inbound ERP sync status of an entity: when each integration last\nsynchronized (checked) the entity against the ERP, and when it last\nactually changed it. `last_synced_at` also advances on no-op checks —\nevents that were received and evaluated but changed nothing — which by\ndesign leave no trace on the entity itself (no activity feed entry, no\n`_updated_at` bump). Use it to tell whether an entity is up to date with\nthe ERP. Returns an empty list for entities no inbound use case has\nprocessed. Org-scoped via the caller's token.\n",
+        "tags": [
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "entityId",
+            "in": "path",
+            "required": true,
+            "description": "The entity ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "integration_id",
+            "in": "query",
+            "required": false,
+            "description": "Narrow the result to a single integration",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved entity sync status",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EntitySyncStatusResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/integrations/{integrationId}/outbound/messages/poll": {
       "post": {
         "operationId": "pollOutboundMessages",
@@ -5262,7 +5476,7 @@
                 "additionalProperties": true
               }
             ],
-            "description": "The object data payload - can be either a serialized string or a direct JSON object",
+            "description": "The object data payload - can be either a serialized string or a direct JSON object.\n\nFor events routed to a mapped (default) use case this is the raw ERP object; the use\ncase's mapping configuration transforms it into entity updates.\n\nFor events routed to a use case whose configuration has `direct: true`, the payload\nMUST be a `DirectPayload` (as an object, or a JSON string): a versioned envelope of\npre-mapped entity and meter reading operations that skip the mapping engine entirely.\nDirect use cases accept JSON only - `format: \"xml\"` events are rejected.\n",
             "example": "{\"id\":\"BP10001\",\"name\":\"Acme Corporation\",\"type\":\"organization\",\"tax_id\":\"DE123456789\",\"status\":\"active\"}"
           },
           "use_case_slug": {
@@ -6064,6 +6278,10 @@
         "type": "object",
         "description": "Configuration for inbound use cases (ERP to epilot)",
         "properties": {
+          "direct": {
+            "type": "boolean",
+            "description": "Enables direct mode for this use case. When `true`, every event routed to this use\ncase must carry a `DirectPayload` - pre-mapped entity and meter reading operations -\ninstead of raw ERP data, and the mapping engine is skipped entirely. Everything else\nin the inbound pipeline (deduplication, ordering, create-vs-update resolution,\nrelation resolution, monitoring) behaves exactly as in mapped mode.\n\nIn direct mode, `entities` doubles as an optional allowlist: when non-empty, each\noperation's `entity_slug` must match an entry's `entity_schema`, and when that entry\ndeclares `unique_ids`, the operation's unique-id keys must be exactly that set (or\njust `_id`). Entries need only `entity_schema` and `unique_ids` - `fields` is not\nrequired and is ignored. `meter_readings` is ignored in direct mode.\n\nFlag changes take up to 5 minutes to propagate (configuration cache).\n"
+          },
           "entities": {
             "type": "array",
             "description": "Array of entity configurations for this event",
@@ -6121,8 +6339,7 @@
         "type": "object",
         "required": [
           "entity_schema",
-          "unique_ids",
-          "fields"
+          "unique_ids"
         ],
         "properties": {
           "entity_schema": {
@@ -6168,7 +6385,7 @@
           },
           "fields": {
             "type": "array",
-            "description": "Field mapping definitions",
+            "description": "Field mapping definitions. Required for mapped-mode entity configurations; may be\nomitted for allowlist entries of a `direct: true` use case, where no mapping runs.\n",
             "items": {
               "$ref": "#/components/schemas/IntegrationEntityField"
             }
@@ -8661,52 +8878,90 @@
           }
         }
       },
-      "EntityUpdate": {
+      "DirectPayload": {
         "type": "object",
+        "description": "The payload of an ERP event routed to a `direct: true` use case: a versioned envelope of\npre-mapped operations that skip the mapping engine. Sent as the `payload` of an\n`ErpEventV3` - either as a JSON object or as a JSON string (`format` must be `json`;\nXML is rejected for direct use cases).\n\nThe schema is strict: unknown keys on the envelope or on any operation are rejected with\nan error naming the offending path. Attribute values, by contrast, pass through to the\nentity verbatim (except `$relation` / `$relation_ref` envelopes, which are validated and\nresolved).\n\nOne event lands as one queue message, so the whole event (including this payload) must\nstay within the 256 KiB message budget. Identical consecutive payloads within 5 minutes\ncan be deduplicated by the queue - use the event's `deduplication_id` deliberately when\nre-sending identical data.\n",
         "required": [
-          "entity_slug",
-          "unique_identifiers",
-          "attributes",
-          "mode"
+          "version",
+          "operations"
         ],
         "properties": {
-          "entity_slug": {
+          "version": {
             "type": "string",
-            "description": "The entity type slug"
+            "enum": [
+              "1"
+            ],
+            "description": "Version of the direct payload contract. Currently only `\"1\"` is supported; an\nunsupported version is rejected with `DIRECT_VERSION_UNSUPPORTED`.\n"
           },
-          "unique_identifiers": {
-            "type": "object",
-            "description": "Unique identifier mappings for this entity",
-            "additionalProperties": true
+          "operations": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 100,
+            "description": "The operations to apply, in order. At most 100 operations per event. Each item is\neither an entity operation (`type` omitted or `\"entity\"`) or a meter reading\noperation (`type: \"meter_reading\"`).\n",
+            "items": {
+              "anyOf": [
+                {
+                  "$ref": "#/components/schemas/DirectEntityOperation"
+                },
+                {
+                  "$ref": "#/components/schemas/DirectMeterReadingOperation"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "DirectEntityOperation": {
+        "type": "object",
+        "description": "A single pre-mapped entity operation: upserts, soft-deletes, or purges one entity,\nidentified by its unique ids. Produces the same internal update as a mapped-mode entity\nconfiguration, so create-vs-update resolution, relation resolution, ordering, and\nmonitoring behave identically.\n",
+        "required": [
+          "entity_slug",
+          "unique_ids"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "entity"
+            ],
+            "description": "Operation discriminator. Optional - an operation without `type` is an entity operation."
           },
-          "attributes": {
-            "type": "object",
-            "description": "Mapped attribute values",
-            "additionalProperties": true
+          "entity_slug": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Target entity schema slug (e.g. `contact`, `contract`).",
+            "example": "contract"
           },
-          "pricing": {
+          "unique_ids": {
             "type": "object",
-            "description": "Present when the entity mapping has a `pricing` block. Echoes the pricing configuration and the data extracted for it, so mapping authors can see what would be sent to the pricing service.",
-            "required": [
-              "config",
-              "data"
-            ],
-            "properties": {
-              "config": {
-                "type": "object",
-                "additionalProperties": true,
-                "description": "The pricing configuration from the entity mapping"
-              },
-              "data": {
-                "type": "array",
-                "description": "The pricing input data extracted from the payload",
-                "items": {
-                  "type": "object",
-                  "additionalProperties": true
+            "minProperties": 1,
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
                 }
-              }
+              ]
+            },
+            "description": "Attribute values that uniquely identify this entity, as `{ attribute: value }`.\nValues may be strings or numbers (numbers are coerced to strings); values that are\nempty after trimming are rejected. Use `_id` as the sole key to reference an entity\ndirectly by its epilot id.\n\nUnlike mapped mode, the unique-id ATTRIBUTE NAMES are given directly - there is no\nfield-to-attribute mapping step.\n",
+            "example": {
+              "contract_number": "CTR-001"
             }
           },
+          "unique_id_types": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string",
+              "enum": [
+                "email",
+                "phone"
+              ]
+            },
+            "description": "Optional per-field type hints for repeatable unique-id fields (`email` / `phone`),\nneeded so lookups search the repeatable storage format correctly. When omitted, the\nserver derives the types from the entity schema; explicit values always win over\nderivation.\n"
+          },
           "mode": {
             "type": "string",
             "enum": [
@@ -8714,20 +8969,586 @@
               "delete",
               "purge"
             ],
-            "description": "Effective operation mode applied to this entity at runtime. `upsert-prune-scope-purge` / `upsert-prune-scope-delete` configurations report `upsert` here, because the individual entities in the payload are upserted — the destructive part of those modes is reported separately in `prune_scope_updates`. For `delete` / `purge`, `attributes` are still mapped and returned but ignored at runtime: only `unique_identifiers` are used to locate the entity to remove."
+            "default": "upsert",
+            "description": "Operation mode: `upsert` creates or updates the entity (default), `delete` soft\ndeletes it, `purge` removes it permanently. For `delete` / `purge`, `attributes`\nmay be omitted - only `unique_ids` are used to locate the entity.\n"
+          },
+          "attributes": {
+            "type": "object",
+            "description": "Attribute values to write, keyed by attribute name. Required when `mode` is `upsert`\n(an empty object is allowed); optional for `delete` / `purge`.\n\nValues are written verbatim - the server does not validate them against the entity\nschema (attributes not defined in the schema are stored but not indexed; the\nsimulation endpoint surfaces warnings for unique-id fields missing from the schema).\nTwo envelope forms receive special treatment: `$relation` values\n(`DirectRelationValue`) and `$relation_ref` values (`DirectRelationRefValue`) are\nvalidated and resolved to entity relations.\n",
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "$ref": "#/components/schemas/DirectRelationValue"
+                },
+                {
+                  "$ref": "#/components/schemas/DirectRelationRefValue"
+                },
+                {
+                  "description": "Any other JSON value - written to the entity attribute verbatim."
+                }
+              ]
+            }
           }
         }
       },
-      "MeterReadingUpdate": {
+      "DirectMeterReadingOperation": {
         "type": "object",
+        "description": "A single pre-mapped meter reading operation: upserts or deletes one reading on a meter\n(and optionally a specific counter), identified by their unique ids. Produces the same\ninternal update as a mapped-mode meter reading configuration.\n",
         "required": [
+          "type",
           "meter",
-          "attributes",
-          "mode"
+          "attributes"
         ],
+        "additionalProperties": false,
         "properties": {
-          "meter": {
-            "type": "object",
+          "type": {
+            "type": "string",
+            "enum": [
+              "meter_reading"
+            ],
+            "description": "Operation discriminator. Required for meter reading operations."
+          },
+          "meter": {
+            "type": "object",
+            "required": [
+              "unique_ids"
+            ],
+            "additionalProperties": false,
+            "description": "Reference to the meter this reading belongs to.",
+            "properties": {
+              "unique_ids": {
+                "type": "object",
+                "minProperties": 1,
+                "additionalProperties": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "number"
+                    }
+                  ]
+                },
+                "description": "Attribute values that uniquely identify the meter, as `{ attribute: value }`.",
+                "example": {
+                  "meter_number": "M-001"
+                }
+              }
+            }
+          },
+          "counter": {
+            "type": "object",
+            "required": [
+              "unique_ids"
+            ],
+            "additionalProperties": false,
+            "description": "Optional reference to the meter counter (register) the reading belongs to. Required\nwhen `reading_matching` is `strict-date`.\n",
+            "properties": {
+              "unique_ids": {
+                "type": "object",
+                "minProperties": 1,
+                "additionalProperties": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "number"
+                    }
+                  ]
+                },
+                "description": "Attribute values that uniquely identify the counter, as `{ attribute: value }`.",
+                "example": {
+                  "obis_number": "1-0:1.8.0"
+                }
+              }
+            }
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "upsert",
+              "delete"
+            ],
+            "default": "upsert",
+            "description": "Operation mode: `upsert` creates or updates the reading (default), `delete` removes it."
+          },
+          "reading_matching": {
+            "type": "string",
+            "enum": [
+              "external_id",
+              "strict-date"
+            ],
+            "description": "Strategy for matching this reading against existing readings. `external_id` (the\ndefault) matches by the reading's `external_id`; `strict-date` matches by meter +\ncounter + direction + date and REQUIRES `counter`. Useful when readings originate in\nthe portal and are echoed back by the ERP with truncated timestamps.\n"
+          },
+          "attributes": {
+            "type": "object",
+            "required": [
+              "external_id",
+              "timestamp",
+              "source",
+              "value"
+            ],
+            "description": "The reading data. Additional keys (e.g. `direction`, `reason`, `read_by`, `status`,\n`metadata`) pass through to the metering service verbatim.\n",
+            "properties": {
+              "external_id": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ],
+                "description": "External identifier of the reading (numbers are coerced to strings)."
+              },
+              "timestamp": {
+                "type": "string",
+                "description": "When the reading was taken. ISO 8601 - either `YYYY-MM-DD` or\n`YYYY-MM-DDTHH:mm:ss` (optional fractional seconds and `Z` / `±HH:mm` offset).\nOther formats (e.g. `DD.MM.YYYY`, epoch numbers) are rejected.\n",
+                "example": "2026-08-24T06:00:00Z"
+              },
+              "source": {
+                "type": "string",
+                "enum": [
+                  "ECP",
+                  "ERP",
+                  "360",
+                  "journey-submission"
+                ],
+                "description": "Origin system of the reading."
+              },
+              "value": {
+                "oneOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "string"
+                  }
+                ],
+                "description": "The reading value - a number, or a numeric string (coerced to a number)."
+              }
+            }
+          }
+        }
+      },
+      "DirectRelationValue": {
+        "type": "object",
+        "description": "An entity attribute value that establishes relations to other entities. Written on any\nattribute inside a direct entity operation's `attributes`.\n\nTwo forms are accepted: a bare array of items (shorthand for `_set`, i.e. replace), or\nan object with EXACTLY ONE of the operations `_set` (replace), `_append` (merge,\ndeduplicated by entity id), `_append_all` (merge without deduplication). No other\noperation keys are accepted.\n",
+        "required": [
+          "$relation"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "$relation": {
+            "oneOf": [
+              {
+                "type": "array",
+                "description": "Shorthand for `_set` - replaces the attribute's relations with these items.",
+                "items": {
+                  "$ref": "#/components/schemas/DirectRelationItem"
+                }
+              },
+              {
+                "type": "object",
+                "description": "Exactly one of `_set`, `_append`, `_append_all` must be given.",
+                "additionalProperties": false,
+                "properties": {
+                  "_set": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/DirectRelationItem"
+                    }
+                  },
+                  "_append": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/DirectRelationItem"
+                    }
+                  },
+                  "_append_all": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/DirectRelationItem"
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        }
+      },
+      "DirectRelationItem": {
+        "type": "object",
+        "description": "One relation target: either an already-resolved reference (`entity_id`), or a lookup by\nunique ids (`schema` + `unique_ids`, resolved by the pipeline like any other unique-id\nlookup, including stub creation and retry when the target does not exist yet). The two\nforms are mutually exclusive. Use `_id` as the sole `unique_ids` key for a direct-id\nlookup.\n",
+        "additionalProperties": false,
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "description": "Epilot entity id of the relation target. Must not be combined with `schema` / `unique_ids`."
+          },
+          "schema": {
+            "type": "string",
+            "description": "Entity schema slug of the relation target. Required when `entity_id` is not given.",
+            "example": "contact"
+          },
+          "unique_ids": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            },
+            "description": "Attribute values that uniquely identify the target. Required when `entity_id` is not given.",
+            "example": {
+              "customer_number": "CUST-12345"
+            }
+          },
+          "unique_id_types": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string",
+              "enum": [
+                "email",
+                "phone"
+              ]
+            },
+            "description": "Optional per-field type hints for repeatable unique-id fields, as on the entity operation."
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional relation tags (e.g. `primary`, `billing`)."
+          }
+        }
+      },
+      "DirectRelationRefValue": {
+        "type": "object",
+        "description": "An entity attribute value that references an ITEM INSIDE a repeatable attribute of\nanother entity - for example one address out of a contact's `address` list. The target\nentity is looked up by unique ids, then the item at `path` matching `value` is\nreferenced (creating it when missing).\n\nThe same operation envelope as `$relation` applies: a bare array is shorthand for\n`_set`, otherwise exactly one of `_set`, `_append`, `_append_all`.\n",
+        "required": [
+          "$relation_ref"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "$relation_ref": {
+            "oneOf": [
+              {
+                "type": "array",
+                "description": "Shorthand for `_set`.",
+                "items": {
+                  "$ref": "#/components/schemas/DirectRelationRefItem"
+                }
+              },
+              {
+                "type": "object",
+                "description": "Exactly one of `_set`, `_append`, `_append_all` must be given.",
+                "additionalProperties": false,
+                "properties": {
+                  "_set": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/DirectRelationRefItem"
+                    }
+                  },
+                  "_append": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/DirectRelationRefItem"
+                    }
+                  },
+                  "_append_all": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/DirectRelationRefItem"
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        }
+      },
+      "DirectRelationRefItem": {
+        "type": "object",
+        "description": "One relation-ref target - the entity to look up, and the repeatable item to reference on it.",
+        "required": [
+          "schema",
+          "unique_ids",
+          "path",
+          "value"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "schema": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Entity schema slug of the target entity.",
+            "example": "contact"
+          },
+          "unique_ids": {
+            "type": "object",
+            "minProperties": 1,
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            },
+            "description": "Attribute values that uniquely identify the target entity."
+          },
+          "unique_id_types": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string",
+              "enum": [
+                "email",
+                "phone"
+              ]
+            },
+            "description": "Optional per-field type hints for repeatable unique-id fields."
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The attribute on the TARGET entity that holds the repeatable array (e.g. `address`)."
+          },
+          "value": {
+            "description": "The item to match (or create) at `path` - e.g. an address object.",
+            "example": {
+              "street": "Main Street",
+              "city": "Berlin"
+            }
+          }
+        }
+      },
+      "DirectSimulationRequest": {
+        "type": "object",
+        "description": "Request for a direct-mode dry run: the `direct: true` use case configuration to test\nagainst, and the payload to validate and translate.\n",
+        "required": [
+          "event_configuration",
+          "payload"
+        ],
+        "properties": {
+          "event_configuration": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              }
+            ],
+            "description": "The direct use case configuration to simulate against. `direct` must be `true`;\n`entities` acts as the optional allowlist exactly as at runtime. This is the same\nconfiguration format stored on the inbound use case resource, so a configuration can\nbe tested before saving it.\n"
+          },
+          "payload": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "The direct payload as a JSON string (as it would be sent in the event's `payload`)."
+              },
+              {
+                "$ref": "#/components/schemas/DirectPayload"
+              }
+            ],
+            "description": "The direct payload to validate - a `DirectPayload` object, or its JSON string form."
+          }
+        }
+      },
+      "DirectSimulationResponse": {
+        "type": "object",
+        "description": "Result of a direct-mode dry run. `valid: false` responses list EVERY violation found\nacross all operations in `errors`. `valid: true` responses preview the internal updates\nthe pipeline would apply, plus non-blocking `warnings`.\n",
+        "required": [
+          "valid",
+          "errors"
+        ],
+        "properties": {
+          "valid": {
+            "type": "boolean",
+            "description": "Whether the payload would be accepted by the ingest endpoint."
+          },
+          "errors": {
+            "type": "array",
+            "description": "All validation errors found. Empty when `valid` is `true`.",
+            "items": {
+              "$ref": "#/components/schemas/DirectSimulationError"
+            }
+          },
+          "warnings": {
+            "type": "array",
+            "description": "Non-blocking findings - e.g. unique-id fields not defined in the target entity\nschema (lookups would never match), or a failed server-side unique-id type\nderivation.\n",
+            "items": {
+              "$ref": "#/components/schemas/MappingSimulationWarning"
+            }
+          },
+          "entity_updates": {
+            "type": "array",
+            "description": "The translated internal entity updates, exactly as the pipeline would process them.\nOnly present when `valid` is `true`.\n",
+            "items": {
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/EntityUpdate"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "unique_identifiers_metadata": {
+                      "type": "object",
+                      "description": "Per-field metadata for repeatable unique-id fields - explicit\n`unique_id_types` merged with server-side schema derivation. Absent when\nno field resolved to a repeatable type.\n",
+                      "additionalProperties": {
+                        "type": "object",
+                        "properties": {
+                          "fieldType": {
+                            "type": "string",
+                            "enum": [
+                              "email",
+                              "phone"
+                            ]
+                          },
+                          "index": {
+                            "type": "integer"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "meter_reading_updates": {
+            "type": "array",
+            "description": "The translated internal meter reading updates. Only present when `valid` is `true`.\n",
+            "items": {
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/MeterReadingUpdate"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "_config": {
+                      "type": "object",
+                      "description": "Per-reading pipeline configuration carried by the operation.",
+                      "properties": {
+                        "reading_matching": {
+                          "type": "string",
+                          "enum": [
+                            "external_id",
+                            "strict-date"
+                          ]
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      "DirectSimulationError": {
+        "type": "object",
+        "description": "One validation error found during a direct-mode dry run.",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "enum": [
+              "DIRECT_PAYLOAD_INVALID",
+              "DIRECT_VERSION_UNSUPPORTED",
+              "DIRECT_ENTITY_NOT_ALLOWED"
+            ],
+            "description": "Error class, matching the monitoring codes the ingest pipeline emits:\n`DIRECT_PAYLOAD_INVALID` (schema violation, JSON parse failure, or XML format),\n`DIRECT_VERSION_UNSUPPORTED` (unknown payload `version`),\n`DIRECT_ENTITY_NOT_ALLOWED` (entity or unique-id keys not permitted by the use\ncase's allowlist).\n"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable description, including the path of the offending element."
+          },
+          "operation_index": {
+            "type": "integer",
+            "description": "Zero-based index of the operation the error refers to, when attributable to one."
+          }
+        }
+      },
+      "EntityUpdate": {
+        "type": "object",
+        "required": [
+          "entity_slug",
+          "unique_identifiers",
+          "attributes",
+          "mode"
+        ],
+        "properties": {
+          "entity_slug": {
+            "type": "string",
+            "description": "The entity type slug"
+          },
+          "unique_identifiers": {
+            "type": "object",
+            "description": "Unique identifier mappings for this entity",
+            "additionalProperties": true
+          },
+          "attributes": {
+            "type": "object",
+            "description": "Mapped attribute values",
+            "additionalProperties": true
+          },
+          "pricing": {
+            "type": "object",
+            "description": "Present when the entity mapping has a `pricing` block. Echoes the pricing configuration and the data extracted for it, so mapping authors can see what would be sent to the pricing service.",
+            "required": [
+              "config",
+              "data"
+            ],
+            "properties": {
+              "config": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "The pricing configuration from the entity mapping"
+              },
+              "data": {
+                "type": "array",
+                "description": "The pricing input data extracted from the payload",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "upsert",
+              "delete",
+              "purge"
+            ],
+            "description": "Effective operation mode applied to this entity at runtime. `upsert-prune-scope-purge` / `upsert-prune-scope-delete` configurations report `upsert` here, because the individual entities in the payload are upserted — the destructive part of those modes is reported separately in `prune_scope_updates`. For `delete` / `purge`, `attributes` are still mapped and returned but ignored at runtime: only `unique_identifiers` are used to locate the entity to remove."
+          }
+        }
+      },
+      "MeterReadingUpdate": {
+        "type": "object",
+        "required": [
+          "meter",
+          "attributes",
+          "mode"
+        ],
+        "properties": {
+          "meter": {
+            "type": "object",
             "required": [
               "$entity_unique_ids"
             ],
@@ -9152,6 +9973,82 @@
           }
         }
       },
+      "EntitySyncStatusResponse": {
+        "type": "object",
+        "required": [
+          "entity_id",
+          "sync_states"
+        ],
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The entity the sync states belong to"
+          },
+          "sync_states": {
+            "type": "array",
+            "description": "One entry per integration that has processed an inbound event for the entity",
+            "items": {
+              "$ref": "#/components/schemas/EntitySyncState"
+            }
+          }
+        }
+      },
+      "EntitySyncState": {
+        "type": "object",
+        "required": [
+          "entity_id",
+          "integration_id",
+          "entity_slug",
+          "last_synced_at",
+          "last_operation"
+        ],
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The entity ID"
+          },
+          "integration_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The integration that synchronized the entity"
+          },
+          "entity_slug": {
+            "type": "string",
+            "description": "The entity schema slug",
+            "example": "contract"
+          },
+          "use_case_id": {
+            "type": "string",
+            "description": "The inbound use case that last processed the entity"
+          },
+          "last_synced_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Last time an inbound ERP event for this entity was processed —\nincluding no-op checks that changed nothing on the entity.\n"
+          },
+          "last_changed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Last time an inbound ERP event actually changed the entity (create/patch/delete)"
+          },
+          "last_operation": {
+            "type": "string",
+            "enum": [
+              "create",
+              "patch",
+              "delete",
+              "no-op"
+            ],
+            "description": "Outcome of the most recent inbound sync check"
+          },
+          "last_event_id": {
+            "type": "string",
+            "description": "The event ID of the most recent inbound sync check"
+          }
+        }
+      },
       "OutboundStatusResponse": {
         "type": "object",
         "required": [

package/dist/bin/epilot.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "../chunk-LU2DXHM7.js";
+} from "../chunk-DVATEMSL.js";
 
 // bin/epilot.ts
 import { runMain } from "citty";
@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.127",
+    version: "0.1.128",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -30,8 +30,8 @@ var main = defineCommand({
     auth: () => import("../auth-WMXFMPWE.js").then((m) => m.default),
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
-    completion: () => import("../completion-MLZIPM5I.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-D4YUJRJS.js").then((m) => m.default),
+    completion: () => import("../completion-QZPBFCMA.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-XUKKPWDE.js").then((m) => m.default),
     "access-token": () => import("../access-token-WWE6BDJH.js").then((m) => m.default),
     address: () => import("../address-EH3C4CVB.js").then((m) => m.default),
     "address-suggestions": () => import("../address-suggestions-RRSLOBFW.js").then((m) => m.default),
@@ -134,13 +134,13 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.127" : (await null).default.version;
+var VERSION = true ? "0.1.128" : (await null).default.version;
 var reorderedArgv = hoistFlagsAfterSubcommand(process.argv.slice(2));
 process.argv = [process.argv[0], process.argv[1], ...reorderedArgv];
 var args = process.argv.slice(2);
 var completionsIdx = args.indexOf("--_completions");
 if (completionsIdx >= 0) {
-  const { handleCompletions } = await import("../completion-MLZIPM5I.js");
+  const { handleCompletions } = await import("../completion-QZPBFCMA.js");
   handleCompletions(args[completionsIdx + 1], args[completionsIdx + 2]);
   process.exit(0);
 }

package/dist/{chunk-LU2DXHM7.js → chunk-DVATEMSL.js}

@@ -881,7 +881,7 @@ var API_LIST = [
     kebabName: "integration-toolkit",
     title: "Integration Toolkit API",
     serverUrl: "https://integration-toolkit.sls.epilot.io",
-    operationCount: 68,
+    operationCount: 70,
     operationIds: [
       "acknowledgeTracking",
       "triggerErp",
@@ -889,6 +889,7 @@ var API_LIST = [
       "processErpUpdatesEventsV2",
       "processErpUpdatesEventsV3",
       "simulateMappingV2",
+      "simulateDirect",
       "simulateMapping",
       "listIntegrations",
       "createIntegration",
@@ -924,6 +925,7 @@ var API_LIST = [
       "getMonitoringStats",
       "getMonitoringTimeSeries",
       "getOutboundStatus",
+      "getEntitySyncStatus",
       "pollOutboundMessages",
       "ackOutboundMessages",
       "listOutboundDlqMessages",

package/dist/{completion-MLZIPM5I.js → completion-QZPBFCMA.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "./chunk-LU2DXHM7.js";
+} from "./chunk-DVATEMSL.js";
 import {
   DIM,
   GREEN,

package/dist/{upgrade-D4YUJRJS.js → upgrade-XUKKPWDE.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.127";
+  if (true) return "0.1.128";
   try {
     const output = execSync("npm ls -g @epilot/cli --depth=0 --json 2>/dev/null", {
       encoding: "utf-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/cli",
-  "version": "0.1.127",
+  "version": "0.1.128",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {