@epilot/entity-client 7.2.1 → 7.3.0

package/dist/openapi.json

@@ -1419,6 +1419,9 @@
           {
             "$ref": "#/components/parameters/HydrateEntitiesQueryParam"
           },
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "in": "query",
             "name": "fields",
@@ -1568,6 +1571,9 @@
           },
           {
             "$ref": "#/components/parameters/HydrateEntitiesQueryParam"
+          },
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
           }
         ],
         "responses": {
@@ -1776,6 +1782,9 @@
           "Entities"
         ],
         "parameters": [
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "name": "input",
             "in": "query",
@@ -1944,6 +1953,9 @@
           "Activity"
         ],
         "parameters": [
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "$ref": "#/components/parameters/ActivityIdPathParam"
           },
@@ -2140,6 +2152,9 @@
           "Entities"
         ],
         "parameters": [
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "$ref": "#/components/parameters/EntitySlugPathParam"
           },
@@ -2173,6 +2188,9 @@
           "Activity"
         ],
         "parameters": [
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "$ref": "#/components/parameters/EntitySlugPathParam"
           },
@@ -2325,6 +2343,9 @@
           {
             "$ref": "#/components/parameters/HydrateEntitiesQueryParam"
           },
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "$ref": "#/components/parameters/IncludeReverseQueryParam"
           },
@@ -2551,6 +2572,9 @@
           {
             "$ref": "#/components/parameters/HydrateEntitiesQueryParam"
           },
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "in": "query",
             "name": "query",
@@ -2620,6 +2644,9 @@
           {
             "$ref": "#/components/parameters/HydrateEntitiesQueryParam"
           },
+          {
+            "$ref": "#/components/parameters/AnonymizeQueryParam"
+          },
           {
             "$ref": "#/components/parameters/IncludeReverseDeprecatedQueryParam"
           },
@@ -2940,6 +2967,69 @@
         }
       }
     },
+    "/v1/entity:abortImport": {
+      "post": {
+        "operationId": "abortEntityImport",
+        "summary": "Abort a running entity import",
+        "description": "Asks a running import to stop. Rows already imported are **kept** - this is a stop, not a\nrollback - and the job still produces its result reports for everything that landed before\nthe stop, then reaches the terminal status `CANCELLED`.\n\nThe stop is cooperative: the worker notices the request at its next batch boundary, so the\njob typically reaches `CANCELLED` within seconds. Poll `POST /v1/entity:import` with the\n`job_id` as usual to observe it.\n\nIdempotent - aborting an already-aborted or already-finished job is not an error.\n",
+        "tags": [
+          "Import-Export"
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "job_id",
+            "required": true,
+            "description": "The ID of the import job to stop.",
+            "schema": {
+              "$ref": "#/components/schemas/ExportJobId"
+            }
+          },
+          {
+            "in": "query",
+            "name": "schema",
+            "required": true,
+            "description": "Slug of the schema being imported, used to authorize the caller.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "description": "The stop was requested. The job is still running until the worker picks the request up.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "description": "The job status at the time of the request."
+                    },
+                    "jobPollId": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request"
+          },
+          "403": {
+            "description": "Forbidden"
+          },
+          "404": {
+            "description": "No such import job"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequestsError"
+          }
+        }
+      }
+    },
     "/v1/entity/views": {
       "get": {
         "operationId": "listSavedViews",
@@ -2990,6 +3080,15 @@
               "maximum": 250
             }
           },
+          {
+            "in": "query",
+            "name": "q",
+            "description": "Free-text search on the saved view name (case-insensitive)",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
           {
             "in": "query",
             "name": "fields",
@@ -3158,7 +3257,10 @@
         ],
         "responses": {
           "200": {
-            "description": "List of all available saved views"
+            "description": "The saved view was deleted"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFoundError"
           },
           "429": {
             "$ref": "#/components/responses/TooManyRequestsError"
@@ -3845,7 +3947,7 @@
               "description": "ISO 8601 timestamp to filter jobs created after this time (e.g., 2023-01-01T00:00:00Z).",
               "type": "string",
               "format": "date-time",
-              "example": "2023-01-01T00:00:00Z"
+              "example": "2023-01-01T00:00:00.000Z"
             }
           },
           {
@@ -4967,6 +5069,34 @@
                     "example": true
                   }
                 }
+              },
+              "grid_layout": {
+                "type": "object",
+                "description": "Widget-grid layout for the entity-details page (builder-authored); columns/cells drive the grid geometry.",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "description": "Identifier of the chosen grid-layout preset."
+                  },
+                  "columns": {
+                    "type": "number",
+                    "description": "Number of columns in the widget grid."
+                  },
+                  "cells": {
+                    "type": "array",
+                    "description": "Per-cell column span, positionally paired with the widgets in order.",
+                    "items": {
+                      "type": "number"
+                    }
+                  }
+                }
+              },
+              "widget_order": {
+                "type": "array",
+                "description": "Ordered list of widget ids controlling the entity-details widget-grid order. Each id is a capability widget's `component` (or `summary` for the synthesized summary card); widgets absent from the list keep their natural order at the end.",
+                "items": {
+                  "type": "string"
+                }
               }
             }
           },
@@ -5094,6 +5224,14 @@
             "items": {
               "$ref": "#/components/schemas/GroupHeadline"
             }
+          },
+          "conditions": {
+            "type": "array",
+            "nullable": true,
+            "description": "Dimensions that conditional variants of this entity type are keyed by.\n\nAbsent or `null` means entities of this type are not conditional. Attributes whose\nvalues a variant may override are marked with `variant_overridable`.\n",
+            "items": {
+              "$ref": "#/components/schemas/ConditionDefinition"
+            }
           }
         },
         "required": [
@@ -5523,6 +5661,11 @@
             "type": "boolean",
             "default": false
           },
+          "variant_overridable": {
+            "type": "boolean",
+            "default": false,
+            "description": "Allow conditional variants of the entity to override this attribute's value.\nOnly meaningful on schemas that declare `conditions`. Unflagged attributes stay\nfixed on the base entity.\n"
+          },
           "default_value": {},
           "group": {
             "description": "Which group the attribute should appear in. Accepts group ID or group name",
@@ -5549,6 +5692,14 @@
             "type": "string",
             "description": "Defines the conditional rendering expression for showing this field.\nWhen a valid expression is parsed, their evaluation defines the visibility of this attribute.\nNote: Empty or invalid expression have no effect on the field visibility.\n"
           },
+          "data_classification": {
+            "type": "string",
+            "enum": [
+              "public",
+              "pii"
+            ],
+            "description": "Data classification of the attribute, used by anonymized responses (`?anonymize=true` or tokens minted with `anonymize: true`).\n\n- `pii`: the attribute value is always anonymized in anonymized responses (use to opt in free-text fields containing personal data)\n- `public`: the attribute value is never anonymized (use to opt out fields matched by built-in defaults, e.g. non-personal identifiers)\n\nWhen unset, built-in defaults apply based on the attribute type (email, phone, address, payment) and a curated list of well-known PII fields.\n"
+          },
           "_purpose": {
             "type": "array",
             "items": {
@@ -5640,14 +5791,12 @@
             "type": "boolean"
           },
           "edit_mode": {
-            "type": "string",
-            "description": "Controls how updates to this attribute are handled.\n- `direct` (default): update is applied immediately. No changeset created.\n- `external`: update creates a changeset, auto-cleared on matching external update (e.g. ERP inbound sync via ?direct=true).\n- `approval`: update creates a changeset, requires explicit human approval.\n",
-            "enum": [
-              "direct",
-              "external",
-              "approval"
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EditMode"
+              }
             ],
-            "default": "direct"
+            "description": "Controls how updates to this attribute are handled. See the `EditMode`\nschema for the per-mode semantics. Defaults to `direct`.\n"
           },
           "edit_mode_config": {
             "description": "Configuration for auto-clear matching on `edit_mode: external` attributes.\n`match_strategy` and `fuzzy_config` are only consulted for `external` mode —\nthey are ignored for `approval` mode, which resolves via explicit\n`:apply` / `:dismiss` endpoints and never auto-clears.\n",
@@ -7117,6 +7266,139 @@
           }
         ]
       },
+      "BaseConditionDefinition": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Stable identity of the condition, generated by the client when the condition is\ncreated. It is what makes a rename distinguishable from a remove + add, so it must\nbe round-tripped unchanged for the lifetime of the condition.\n",
+            "example": "d5839b94-ba20-4225-a78e-76951d352bd6"
+          },
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z0-9_]+$",
+            "description": "The key variant values are stored under. Unique within the schema and immutable\nonce the condition has been saved.\n",
+            "example": "delivery_area"
+          },
+          "label": {
+            "type": "string",
+            "description": "Display label. Always editable.",
+            "example": "Delivery Area"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "label"
+        ]
+      },
+      "ScalarConditionDefinition": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseConditionDefinition"
+          },
+          {
+            "type": "object",
+            "description": "A condition whose value is a plain scalar, with no further configuration.",
+            "properties": {
+              "type": {
+                "type": "string",
+                "description": "Immutable once the condition has been saved.",
+                "enum": [
+                  "string",
+                  "number",
+                  "date",
+                  "daterange",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "type"
+            ]
+          }
+        ]
+      },
+      "SelectConditionDefinition": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseConditionDefinition"
+          },
+          {
+            "type": "object",
+            "description": "A condition whose value is one of a fixed set of options.",
+            "properties": {
+              "type": {
+                "type": "string",
+                "description": "Immutable once the condition has been saved.",
+                "enum": [
+                  "select"
+                ]
+              },
+              "values": {
+                "type": "array",
+                "description": "Selectable options. May be empty while the condition is being configured.",
+                "items": {
+                  "type": "string"
+                },
+                "example": [
+                  "12_months",
+                  "24_months"
+                ]
+              }
+            },
+            "required": [
+              "type"
+            ]
+          }
+        ]
+      },
+      "LocationConditionDefinition": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseConditionDefinition"
+          },
+          {
+            "type": "object",
+            "description": "A condition whose value identifies a place.",
+            "properties": {
+              "type": {
+                "type": "string",
+                "description": "Immutable once the condition has been saved.",
+                "enum": [
+                  "location"
+                ]
+              },
+              "format": {
+                "type": "string",
+                "description": "The shape of the location value. Immutable once the condition has been saved.",
+                "enum": [
+                  "zipcode",
+                  "zipcode_town"
+                ]
+              }
+            },
+            "required": [
+              "type"
+            ]
+          }
+        ]
+      },
+      "ConditionDefinition": {
+        "description": "One dimension that conditional variants of an entity type are keyed by. `type`\ndiscriminates the variants: only a `select` condition carries `values`, and only a\n`location` condition carries `format`.\n",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/ScalarConditionDefinition"
+          },
+          {
+            "$ref": "#/components/schemas/SelectConditionDefinition"
+          },
+          {
+            "$ref": "#/components/schemas/LocationConditionDefinition"
+          }
+        ]
+      },
       "EntitySlug": {
         "description": "URL-friendly identifier for the entity schema",
         "type": "string",
@@ -7581,7 +7863,7 @@
             "readOnly": true,
             "type": "object",
             "nullable": true,
-            "description": "Pending attribute changesets for attributes configured with external or approval edit mode.\nRead-only via normal entity PATCH/PUT operations — cannot be set directly.\nUse the changeset management endpoints to apply or dismiss changesets.\n",
+            "description": "Pending attribute changesets for attributes configured with external or approval edit mode.\n\nThe value shape is `Changeset` (`proposed_value`, `created_at`, `edit_mode`, ...)\nand is what `:apply` / `:dismiss` operate on.\n\nRead-only via normal entity PATCH/PUT operations — those handlers strip `_changesets`\nfrom request bodies. Use the changeset management endpoints to mutate this field.\n",
             "additionalProperties": {
               "$ref": "#/components/schemas/Changeset"
             }
@@ -8092,6 +8374,7 @@
               "from": {},
               "size": {},
               "hydrate": {},
+              "anonymize": {},
               "fields": {},
               "aggs": {},
               "include_deleted": {},
@@ -8176,6 +8459,7 @@
               "from": {},
               "size": {},
               "hydrate": {},
+              "anonymize": {},
               "fields": {},
               "aggs": {},
               "include_deleted": {},
@@ -8400,6 +8684,11 @@
             "description": "When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.",
             "default": false
           },
+          "anonymize": {
+            "type": "boolean",
+            "description": "When true, anonymizes PII in the response: identifiers are replaced with deterministic pseudonyms,\naddresses are generalized and well-known free-text fields are redacted.\nAnonymization is forced (regardless of this parameter) when the access token was created with `anonymize: true`.\n",
+            "default": false
+          },
           "fields": {
             "$ref": "#/components/schemas/FieldsParam"
           },
@@ -9032,6 +9321,9 @@
               }
             }
           },
+          "source_context": {
+            "$ref": "#/components/schemas/EntityOperationSourceContext"
+          },
           "_workflow_origin": {
             "type": "object",
             "description": "Internal property for workflow origin tracking and infinite loop prevention.\nPopulated when an entity update originates from a workflow execution.\nThis allows downstream automation services to prevent circular triggering.\n",
@@ -9045,6 +9337,13 @@
                 "description": "The flow template ID - used to detect and prevent circular triggering"
               }
             }
+          },
+          "_automation_chain": {
+            "type": "array",
+            "description": "Ordered automation flow ids that caused this change; used to break multi-automation trigger loops.",
+            "items": {
+              "type": "string"
+            }
           }
         },
         "required": [
@@ -9053,6 +9352,59 @@
           "operation"
         ]
       },
+      "EntityOperationSourceContext": {
+        "type": "object",
+        "description": "Billing and audit source context for the operation event.",
+        "properties": {
+          "source": {
+            "type": "string",
+            "description": "Normalized source bucket for the operation.",
+            "enum": [
+              "portal",
+              "epilot",
+              "erp",
+              "system",
+              "api",
+              "external",
+              "journey",
+              "automation",
+              "unknown"
+            ]
+          },
+          "source_label": {
+            "type": "string",
+            "description": "Original free-form source label from the caller or changeset, when available."
+          },
+          "source_system": {
+            "type": "string",
+            "description": "Optional upstream system label, for example an ERP system name."
+          },
+          "source_reference": {
+            "type": "string",
+            "description": "Optional upstream change reference."
+          },
+          "actor_type": {
+            "type": "string",
+            "enum": [
+              "user",
+              "portal_user",
+              "api_client",
+              "automation",
+              "system"
+            ]
+          },
+          "actor_id": {
+            "type": "string"
+          },
+          "effective_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "source"
+        ]
+      },
       "BaseActivityItem": {
         "allOf": [
           {
@@ -9194,6 +9546,11 @@
                   "user_id": {
                     "type": "string",
                     "example": "10598"
+                  },
+                  "org_id": {
+                    "type": "string",
+                    "description": "The organization ID of the user who created the view. Used for partner access control.",
+                    "example": "739224"
                   }
                 }
               },
@@ -9374,7 +9731,8 @@
           "message",
           "portal_user",
           "request",
-          "comment"
+          "comment",
+          "user"
         ]
       },
       "TaxonomySearchIncludeArchivedParam": {
@@ -9771,6 +10129,185 @@
           "$ref": "#/components/schemas/Changeset"
         }
       },
+      "MeterReadingChangesetEntry": {
+        "type": "object",
+        "description": "A meter readings changeset entry — service-managed by metering-api.\nStored on `Meter._meter_readings_changeset` array attribute. Each entry mirrors a\nClickHouse meter reading row plus a changeset metadata overlay.\n\nNote: `org_id` is NOT stored on the entry. The entries live on the Meter entity,\nwhich is already org-scoped (`_org`). Round-tripping it would only invite drift;\ndownstream consumers receive the org from the meter / handler context.\n",
+        "required": [
+          "changeset_id",
+          "meter_id",
+          "counter_id",
+          "value",
+          "edit_mode",
+          "created_at"
+        ],
+        "properties": {
+          "value": {
+            "type": "number"
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "feed-in",
+              "feed-out"
+            ]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "meter_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "counter_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "source": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          },
+          "read_by": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "valid",
+              "in-validation",
+              "implausible"
+            ]
+          },
+          "external_id": {
+            "type": "string"
+          },
+          "remark": {
+            "type": "string"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "changeset_id": {
+            "type": "string",
+            "description": "Unique changeset identifier (UUID v4)."
+          },
+          "edit_mode": {
+            "type": "string",
+            "enum": [
+              "external",
+              "approval"
+            ]
+          },
+          "match_strategy": {
+            "type": "string",
+            "enum": [
+              "exact",
+              "fuzzy"
+            ]
+          },
+          "timestamp_tolerance": {
+            "description": "Slack on `reading.timestamp` when metering-api auto-clear matches an\nincoming reading against this pending changeset.\n\nVariants:\n- `'exact'`: strict millisecond equality.\n- `{ type: 'same-day', timezone? }`: strip the time component and\n  compare year-month-day. Optional `timezone` is an IANA name\n  (e.g. `'Europe/Berlin'`); the day is bucketed in that zone.\n  Defaults to UTC when omitted.\n- `{ type: 'within-seconds', seconds }`: symmetric ±N-second window.\n",
+            "oneOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "exact"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type"
+                ],
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "same-day"
+                    ]
+                  },
+                  "timezone": {
+                    "type": "string",
+                    "description": "IANA timezone identifier (e.g. `'Europe/Berlin'`, `'UTC'`).\nWhen omitted, the day is bucketed in UTC.\n"
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "seconds"
+                ],
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "enum": [
+                      "within-seconds"
+                    ]
+                  },
+                  "seconds": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Tolerance in seconds. e.g. 60 = ±1 minute, 3600 = ±1 hour."
+                  }
+                }
+              }
+            ]
+          },
+          "fuzzy_config": {
+            "type": "object",
+            "properties": {
+              "percentage_threshold": {
+                "type": "number"
+              },
+              "absolute_threshold": {
+                "type": "number"
+              }
+            }
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_by": {
+            "$ref": "#/components/schemas/ChangesetCreator"
+          },
+          "previous": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "number"
+              },
+              "direction": {
+                "type": "string",
+                "enum": [
+                  "feed-in",
+                  "feed-out"
+                ]
+              },
+              "timestamp": {
+                "type": "string",
+                "format": "date-time"
+              }
+            }
+          }
+        }
+      },
+      "EditMode": {
+        "type": "string",
+        "description": "Controls whether a write goes through immediately or is held as a pending entry\non the parent entity's `_changesets` map.\n\n- `direct`: write applied immediately. No changeset created.\n- `external`: write held as a pending changeset; auto-cleared on a matching direct/ERP write.\n- `approval`: write held as a pending changeset; requires explicit human apply/dismiss.\n\nUsed at two levels: per-attribute (entity-attribute changesets) and per-capability\n(currently the `meter_readings` capability on the Meter schema, gating reading submissions).\n",
+        "enum": [
+          "direct",
+          "external",
+          "approval"
+        ],
+        "default": "direct"
+      },
       "EditModeConfig": {
         "type": "object",
         "description": "Configuration for `edit_mode: external` auto-clear matching.\nFields here (`match_strategy`, `fuzzy_config`) only take effect when\n`edit_mode` is `external`. They are ignored for `edit_mode: approval`,\nwhich never auto-clears and is resolved exclusively via the\n`:apply` / `:dismiss` changeset endpoints.\n",
@@ -9875,6 +10412,16 @@
       }
     },
     "parameters": {
+      "AnonymizeQueryParam": {
+        "name": "anonymize",
+        "description": "When true, anonymizes PII in the response: identifiers (names, emails, phone numbers, IBANs) are replaced\nwith deterministic pseudonyms (stable within an org), addresses are generalized to postal code / city / country,\nand well-known free-text fields (e.g. note content) are redacted.\n\nUseful for AI agents and data analysis use cases that must not access personal data.\n\nAnonymization is forced (regardless of this parameter) when the access token was created with `anonymize: true`.\n",
+        "in": "query",
+        "required": false,
+        "schema": {
+          "type": "boolean",
+          "default": false
+        }
+      },
       "EntityIdPathParam": {
         "name": "id",
         "description": "Entity id",