@epilot/entity-client 7.2.0 → 7.2.1-rc1

package/dist/openapi.json

@@ -5640,17 +5640,15 @@
             "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 non-direct edit modes. Required when edit_mode is external or approval with fuzzy match strategy.",
+            "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",
             "allOf": [
               {
                 "$ref": "#/components/schemas/EditModeConfig"
@@ -7581,7 +7579,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"
             }
@@ -9729,14 +9727,19 @@
           },
           "edit_mode": {
             "type": "string",
-            "description": "The edit mode that triggered this changeset",
+            "description": "The edit mode that triggered this changeset.\n- `external`: auto-cleared by a matching `?direct=true` write (see `match_strategy`).\n- `approval`: resolved only via explicit `:apply` / `:dismiss` endpoints; never auto-clears.\n",
             "enum": [
               "external",
               "approval"
             ]
           },
           "match_strategy": {
-            "$ref": "#/components/schemas/MatchStrategy"
+            "description": "Match strategy copied from the attribute's `edit_mode_config` at changeset\ncreation time. Only consulted when `edit_mode` is `external`; ignored for\n`approval` (which never auto-clears).\n",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/MatchStrategy"
+              }
+            ]
           },
           "source": {
             "type": "string",
@@ -9766,9 +9769,188 @@
           "$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 non-direct edit modes on an entity attribute.",
+        "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",
         "properties": {
           "match_strategy": {
             "$ref": "#/components/schemas/MatchStrategy"
@@ -9780,7 +9962,7 @@
       },
       "FuzzyConfig": {
         "type": "object",
-        "description": "Configuration for fuzzy match strategies on changeset auto-clearing.",
+        "description": "Configuration for fuzzy auto-clear matching on `edit_mode: external` attributes.\nNot used for `edit_mode: approval`.\n\nType compatibility with attribute shape is enforced at schema save time:\n- scalar string attributes: `suffix`, `digits_only`, `regex`\n- repeatable attributes: `set_equivalent`, `entry_match`, `ignore_fields`, `normalize_phone`\n- relation attributes: `relation_set`\n",
         "required": [
           "type"
         ],
@@ -9793,7 +9975,9 @@
               "digits_only",
               "normalize_phone",
               "ignore_fields",
-              "contains_entry",
+              "set_equivalent",
+              "entry_match",
+              "relation_set",
               "regex"
             ]
           },
@@ -9806,7 +9990,7 @@
             "items": {
               "type": "string"
             },
-            "description": "For type=ignore_fields: field names to exclude when comparing array entries."
+            "description": "For type=ignore_fields and type=set_equivalent: field names to exclude when comparing array entries. `_id` is always stripped by the platform regardless of this config."
           },
           "regex_flags": {
             "type": "string",
@@ -9818,7 +10002,37 @@
           },
           "match_on": {
             "type": "string",
-            "description": "For type=normalize_phone and type=contains_entry: attribute key(s) within array entries to compare on."
+            "description": "For type=normalize_phone: attribute key within array entries to compare on (e.g. 'phone_number')."
+          },
+          "key": {
+            "description": "For type=entry_match: business key(s) within each entry used to match proposed entries against incoming entries.",
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ]
+          },
+          "mode": {
+            "type": "string",
+            "description": "For type=entry_match and type=set_equivalent: how strict the comparison is.\n- `subset` (default for entry_match): every proposed entry must exist in incoming; extra incoming entries are allowed.\n- `exact_set` (default for set_equivalent): the two sides must contain the same entries (order-insensitive, multiset semantics).\n",
+            "enum": [
+              "subset",
+              "exact_set"
+            ]
+          },
+          "ordered": {
+            "type": "boolean",
+            "description": "For type=relation_set: when true, relation order is significant. Defaults to false (order-insensitive)."
+          },
+          "require_tags_match": {
+            "type": "boolean",
+            "description": "For type=relation_set: when true, each relation item's `_tags` must match on both sides (order-insensitive). Defaults to false — `_tags` are stripped before compare."
           },
           "pattern": {
             "type": "string",
@@ -9828,7 +10042,7 @@
       },
       "MatchStrategy": {
         "type": "string",
-        "description": "Strategy for auto-clearing the changeset when an external update is received.\n- `exact`: The inbound value must exactly match the proposed value (deep equality).\n- `fuzzy`: The inbound value is compared using the configured fuzzy algorithm.\n- `any`: Any update to the attribute clears the changeset, regardless of value.\n",
+        "description": "Strategy for auto-clearing a changeset on an `edit_mode: external` attribute\nwhen a direct write (`?direct=true`) arrives — typically an ERP inbound sync.\nIgnored for `edit_mode: approval`, which does not auto-clear and is resolved\nexclusively via the `:apply` / `:dismiss` changeset endpoints.\n- `exact`: The inbound value must exactly match the proposed value (deep equality).\n- `fuzzy`: The inbound value is compared using the configured `fuzzy_config` algorithm.\n- `any`: Any update to the attribute clears the changeset, regardless of value.\n",
         "enum": [
           "exact",
           "fuzzy",
@@ -10074,7 +10288,7 @@
       },
       "DirectQueryParam": {
         "name": "direct",
-        "description": "When true, bypasses changeset interception and applies attribute updates directly.\nUsed by trusted integrations (e.g. ERP inbound sync) to confirm changes and auto-clear matching pending changesets.\nDefaults to false — no breaking change for existing callers.\n",
+        "description": "When true, bypasses changeset interception: attribute values in the payload\nare written directly to the entity regardless of each attribute's `edit_mode`.\nThe write always lands, independently of any auto-clear outcome below.\n\nAfter the direct write, for each attribute in the payload that also has a\npending changeset:\n- `edit_mode: external` — the incoming value is checked against the\n  changeset's `match_strategy` (and `fuzzy_config` when `fuzzy`). On match,\n  `_changesets[attr]` is cleared. On no-match, the write still stands and\n  the changeset stays pending (signalling the ERP/trusted source applied a\n  different correction than originally proposed; resolve via a later\n  matching direct write, or via the `:apply` / `:dismiss` endpoints).\n- `edit_mode: approval` — never auto-cleared. The write lands but the\n  pending changeset remains until explicitly resolved via `:apply` or\n  `:dismiss`.\n\nIntended for trusted integrations (e.g. ERP inbound sync). ERP middleware\nmust always use `?direct=true` — without it, an inbound sync on an\n`external` attribute would create a new changeset instead of confirming\nthe pending one.\n\nDefaults to false — no breaking change for existing callers.\n",
         "in": "query",
         "required": false,
         "schema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/entity-client",
-  "version": "7.2.0",
+  "version": "7.2.1-rc1",
   "description": "JavaScript client library for the epilot Core Entity API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",