@epilot/entity-client 7.4.0 → 7.5.2

package/dist/openapi.json

@@ -75,7 +75,8 @@
           {
             "in": "query",
             "name": "latest",
-            "description": "When true, return the latest version instead of the frozen version for frozen schemas.",
+            "deprecated": true,
+            "description": "No longer has any effect: schema freezing is retired and the latest version is always returned.\n",
             "schema": {
               "type": "boolean",
               "default": false
@@ -161,7 +162,8 @@
           {
             "in": "query",
             "name": "latest",
-            "description": "When true, return the latest version instead of the frozen version for frozen schemas.",
+            "deprecated": true,
+            "description": "No longer has any effect: schema freezing is retired and the latest version is always returned.\n",
             "schema": {
               "type": "boolean",
               "default": false
@@ -223,7 +225,7 @@
       "get": {
         "operationId": "getSchema",
         "summary": "getSchema",
-        "description": "By default gets the current version of the Schema (frozen version if frozen, otherwise latest).\nPass ?latest=true to get the latest version when the schema is frozen.\nPass ?id= to get a specific version by ID.\n",
+        "description": "Gets the latest version of the Schema.\nPass ?id= to get a specific version by ID.\n",
         "tags": [
           "Schemas"
         ],
@@ -241,7 +243,8 @@
           {
             "in": "query",
             "name": "latest",
-            "description": "When true, return the latest version instead of the frozen version for frozen schemas.",
+            "deprecated": true,
+            "description": "No longer has any effect: schema freezing is retired and the latest version is always returned.\n",
             "schema": {
               "type": "boolean",
               "default": false
@@ -267,7 +270,7 @@
       "put": {
         "operationId": "putSchema",
         "summary": "putSchema",
-        "description": "Create or update a schema with a new version.\nWhen the schema is frozen, writes update the latest version without affecting the frozen version.\n",
+        "description": "Create or update a schema with a new version.\n",
         "tags": [
           "Schemas"
         ],
@@ -792,7 +795,8 @@
                       "type": "boolean"
                     },
                     "frozen_version": {
-                      "description": "The version ID that is currently frozen, if any",
+                      "deprecated": true,
+                      "description": "No longer returned: schema freezing is retired.\n",
                       "allOf": [
                         {
                           "$ref": "#/components/schemas/SchemaId"
@@ -815,7 +819,8 @@
       "post": {
         "operationId": "freezeSchema",
         "summary": "freezeSchema",
-        "description": "Freeze a schema at its current version, or at a specific version.\nWhen frozen, getSchema returns the frozen version by default.\nNew edits via putSchema update the latest version without affecting the frozen version.\n",
+        "deprecated": true,
+        "description": "Deprecated no-op: schema freezing is retired and every read returns the latest version.\nReturns the latest version of the schema unchanged. This endpoint will be removed.\n",
         "tags": [
           "Schemas"
         ],
@@ -864,7 +869,8 @@
       "post": {
         "operationId": "unfreezeSchema",
         "summary": "unfreezeSchema",
-        "description": "Unfreeze a schema. Promotes the latest version to the current version for all users.\n",
+        "deprecated": true,
+        "description": "Deprecated: schema freezing is retired. Cleans up a leftover frozen pointer by promoting the\nlatest version to the current version, and succeeds when there is nothing to clean up.\nThis endpoint will be removed.\n",
         "tags": [
           "Schemas"
         ],
@@ -1777,7 +1783,7 @@
       "get": {
         "operationId": "autocomplete",
         "summary": "autocomplete",
-        "description": "Autocomplete entity attributes\n",
+        "description": "Autocomplete entity attributes.\n\nSuggestions are derived from the values **currently stored on entities** the caller is allowed to read.\nA value only shows up while at least one entity carries it, so this endpoint reflects usage, not\nconfiguration.\n\nTo enumerate the label catalogue managed in the Label Builder (including labels that are not\nassigned to any entity yet, and excluding archived ones), use the Taxonomy endpoints instead:\n`POST /v1/entity/taxonomies/classifications:search` (`taxonomiesClassificationsSearch`) or\n`GET /v1/entity/taxonomies/{taxonomySlug}:autocomplete` (`taxonomyAutocomplete`).\n\nFor `attribute=_tags` the distinct values are aggregated across all matching entities, `hits` is the exact\nnumber of distinct values (capped at 1000) and results are ordered by usage. For other attributes the\n1000 most recently updated entities are scanned and `hits` is the number of distinct values found so far.\n",
         "tags": [
           "Entities"
         ],
@@ -1788,7 +1794,7 @@
           {
             "name": "input",
             "in": "query",
-            "description": "Input to autocomplete",
+            "description": "Input to autocomplete (case-insensitive substring match)",
             "schema": {
               "type": "string"
             }
@@ -1821,6 +1827,17 @@
               "minimum": 1,
               "maximum": 250
             }
+          },
+          {
+            "name": "from",
+            "in": "query",
+            "description": "Number of distinct values to skip, for paging through results when `hits` exceeds `size`.\n`from + size` may not exceed 1000.\n",
+            "schema": {
+              "type": "integer",
+              "default": 0,
+              "minimum": 0,
+              "maximum": 999
+            }
           }
         ],
         "responses": {
@@ -1833,6 +1850,7 @@
                   "properties": {
                     "hits": {
                       "type": "number",
+                      "description": "Number of distinct values matching the input. Exact (independent of `size`, capped at 1000) for\n`_tags`; for other attributes the number of distinct values collected so far, which may grow with `size`.\n",
                       "example": 1
                     },
                     "results": {
@@ -3947,7 +3965,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:00.000Z"
+              "example": "2023-01-01T00:00:00Z"
             }
           },
           {
@@ -5126,6 +5144,100 @@
                   "address_map": "full_width",
                   "recent_communications": "one_third_width"
                 }
+              },
+              "custom_tabs": {
+                "type": "array",
+                "description": "Configured tabs that host widgets, shown alongside capability tabs in entity details. Interleaves with capability `EntityDetailsV2:Tab` ui_hooks on a shared `order`: the host merges both lists and sorts by `order`, with capability tabs winning ties. Unlike the header grid, a tab's `widgets` list is the entire membership — a widget's ui_hook `default_visible` is never consulted for tab placement.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": true,
+                  "description": "A single configured tab. `type` discriminates the payload shape; readers must skip an entry whose `type` they don't recognize instead of failing, and writers must round-trip such entries unchanged, so a stable host and a canary host can safely share one schema. Mirrors the same skip-unknown/round-trip contract already used for capability `ui_hooks` entries above.",
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "description": "Generated when the tab is created and never edited afterward, so a blueprint-authored tab and a customer-authored tab can never collide and identity survives a rename.",
+                      "example": "8f14e45f-ceea-467e-a0d6-c8a4ea1c9e6d"
+                    },
+                    "slug": {
+                      "type": "string",
+                      "description": "URL route segment for the tab, derived from `title`. Unique within the schema, and against capability tab ids, since both share one route-segment namespace.",
+                      "example": "sales-overview"
+                    },
+                    "title": {
+                      "type": "string",
+                      "description": "Tab label, authored by the configuring user.",
+                      "example": "Sales Overview"
+                    },
+                    "order": {
+                      "type": "integer",
+                      "description": "Authoritative render position; array position carries no meaning. Shares one ordering space with capability tab ui_hook `order` — at equal `order`, capability tabs sort first.",
+                      "example": 10
+                    },
+                    "icon": {
+                      "type": "string",
+                      "description": "Icon name from the existing entity icon set.",
+                      "example": "person"
+                    },
+                    "type": {
+                      "type": "string",
+                      "description": "Discriminator for the tab's payload. Currently `widgets`, carried by the `widgets` property below; a future tab kind adds its own payload property rather than reusing this one. Deliberately not an enum, so a type introduced by a newer host still round-trips through an older one instead of failing validation.",
+                      "example": "widgets"
+                    },
+                    "widgets": {
+                      "type": "array",
+                      "description": "Payload for `type: widgets`. Membership in this list IS the tab's widget set, in render order — there is no separate visibility map, and a widget's ui_hook `default_visible` is not consulted.",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "description": "Widget id — a capability widget's `component`, or `summary` for the synthesized summary card.",
+                            "example": "next_best_action"
+                          },
+                          "width": {
+                            "type": "string",
+                            "description": "Width for this widget within the tab's grid. Falls back the same way as the header's `widget_widths` when omitted: widget's ui_hook `default_width`, then `full_width`.",
+                            "enum": [
+                              "one_third_width",
+                              "half_width",
+                              "two_third_width",
+                              "full_width"
+                            ]
+                          }
+                        },
+                        "required": [
+                          "id"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "slug",
+                    "title",
+                    "order",
+                    "type"
+                  ]
+                },
+                "example": [
+                  {
+                    "id": "8f14e45f-ceea-467e-a0d6-c8a4ea1c9e6d",
+                    "slug": "sales-overview",
+                    "title": "Sales Overview",
+                    "order": 10,
+                    "type": "widgets",
+                    "widgets": [
+                      {
+                        "id": "next_best_action",
+                        "width": "full_width"
+                      },
+                      {
+                        "id": "recent_communications",
+                        "width": "one_third_width"
+                      }
+                    ]
+                  }
+                ]
               }
             }
           },
@@ -5257,7 +5369,7 @@
           "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",
+            "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 `overridable_attribute`.\n",
             "items": {
               "$ref": "#/components/schemas/ConditionDefinition"
             }
@@ -5300,11 +5412,13 @@
                 }
               },
               "frozen": {
-                "description": "Indicates this schema is currently frozen. Present when the returned version is the frozen version.",
+                "deprecated": true,
+                "description": "No longer returned: schema freezing is retired.\n",
                 "type": "boolean"
               },
               "latest": {
-                "description": "Indicates this is the latest version of the schema. Both frozen and latest can be true if no changes were made since freezing.",
+                "deprecated": true,
+                "description": "No longer returned: every read returns the latest version.\n",
                 "type": "boolean"
               },
               "_summary": {
@@ -5690,10 +5804,10 @@
             "type": "boolean",
             "default": false
           },
-          "variant_overridable": {
+          "overridable_attribute": {
             "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"
+            "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\nAccepted on scalar attributes and on relations — a variant overrides a relation by\nreplacing its whole `$relation` list (e.g. a product's prices). Rejected on system\n(`_`-prefixed), `readonly`, `hidden`, `computed` and `repeatable` attributes.\n"
           },
           "default_value": {},
           "group": {
@@ -7365,15 +7479,36 @@
                   "select"
                 ]
               },
-              "values": {
+              "options": {
                 "type": "array",
-                "description": "Selectable options. May be empty while the condition is being configured.",
+                "description": "Selectable options, in the same shape a `select` attribute's `options` take: a bare\nvalue or a `{ value, title }` object. May be empty while the condition is being\nconfigured.\n",
                 "items": {
-                  "type": "string"
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "value": {
+                          "type": "string"
+                        },
+                        "title": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "value"
+                      ]
+                    }
+                  ]
                 },
                 "example": [
                   "12_months",
-                  "24_months"
+                  {
+                    "value": "24_months",
+                    "title": "24 months"
+                  }
                 ]
               }
             },
@@ -7415,7 +7550,7 @@
         ]
       },
       "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",
+        "description": "One dimension that conditional variants of an entity type are keyed by. `type`\ndiscriminates the variants: only a `select` condition carries `options`, and only a\n`location` condition carries `format`.\n",
         "oneOf": [
           {
             "$ref": "#/components/schemas/ScalarConditionDefinition"
@@ -7477,10 +7612,19 @@
               "$ref": "#/components/schemas/Attribute"
             }
           },
-          "variant_overridable": {
+          "overridable_attribute": {
             "type": "boolean",
             "default": false,
-            "description": "Allow conditional variants of the entity to override the values managed by this\ncapability. Only meaningful on schemas that declare `conditions` and on capabilities\nthat render an attribute group (`EntityAttributes:Group` ui hook), e.g. pricing tiers.\nAttributes carried by the capability opt in individually via their own\n`variant_overridable` flag.\n"
+            "description": "Allow conditional variants to override the fields this capability manages. Only\nmeaningful on schemas that declare `conditions`, and requires `managed_fields`: the\nflag covers exactly what that lists, not the capability's name.\n"
+          },
+          "managed_fields": {
+            "type": "array",
+            "description": "Every entity field this capability writes, including one named after the capability\nitself. With `overridable_attribute`, this is the definitive list of what a variant\nmay override through the capability, applied as a single patch.\n\nFields, not attributes: a capability may write entity fields that have no attribute\ndefinition, so entries need not resolve to one. Where an entry does resolve to an\nattribute, `hidden` and `computed` do not disqualify it.\n",
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9_]+$",
+              "example": "status"
+            }
           },
           "_purpose": {
             "type": "array",

package/dist/schema-model.d.ts

@@ -1,8 +1,27 @@
+import type { Attribute } from './openapi';
+/** Every `type` an entity schema attribute can have. */
+export type AttributeType = NonNullable<Attribute['type']>;
 export declare enum RelationAffinityMode {
-    /**
-     * For strong affinity mode on a relation attribute, deleting or creating the parent or the relation linkage will trigger a CASCADE delete or create to the relation entity itself.
-     * For weak affinity mode on a relation attribute, deleting or creating the parent or the relation linkage will NOT trigger a CASCADE delete or create to the relation entity itself.
-     */
+    /** Deleting or creating the parent or the linkage does NOT cascade to the relation entity. */
     WEAK = "weak",
+    /** Deleting or creating the parent or the linkage cascades to the relation entity. */
     STRONG = "strong"
 }
+/** Types that point at another entity. A repeatable relation is still a relation. */
+export declare const RELATION_ATTRIBUTE_TYPE_LIST: readonly ["relation", "relation_user", "relation_address", "relation_payment_method"];
+/** `string`, not `AttributeType`, so callers can test an unnarrowed `attribute.type`. */
+export declare const RELATION_ATTRIBUTE_TYPES: ReadonlySet<string>;
+/**
+ * Entity attribute types a conditional pricing variant may override (`overridable_attribute`).
+ * An allowlist, so a new scalar type is never overridable by default; a new relation type is, since
+ * relations are overridable by kind. No pricing schema to `satisfies` against — `models.test.ts`
+ * checks these against the entity spec.
+ *
+ * Scalars are overridden value for value. The relation types are overridden as a whole: the
+ * variant's `$relation` list replaces the base entity's, which is how a variant swaps a product's
+ * prices or a composite price's components. They are spread from `RELATION_ATTRIBUTE_TYPE_LIST`
+ * above rather than restated, so the two sets cannot drift.
+ */
+export declare const OVERRIDABLE_ATTRIBUTE_TYPE_LIST: readonly ["string", "number", "currency", "boolean", "date", "datetime", "select", "radio", "multiselect", "checkbox", "country", "tags", "relation", "relation_user", "relation_address", "relation_payment_method"];
+/** `string`, not a literal union, so callers can test an unnarrowed `attribute.type`. */
+export declare const OVERRIDABLE_ATTRIBUTE_TYPES: ReadonlySet<string>;

package/dist/schema-model.js

@@ -1,13 +1,56 @@
 "use strict";
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RelationAffinityMode = void 0;
+exports.OVERRIDABLE_ATTRIBUTE_TYPES = exports.OVERRIDABLE_ATTRIBUTE_TYPE_LIST = exports.RELATION_ATTRIBUTE_TYPES = exports.RELATION_ATTRIBUTE_TYPE_LIST = exports.RelationAffinityMode = void 0;
 var RelationAffinityMode;
 (function (RelationAffinityMode) {
-    /**
-     * For strong affinity mode on a relation attribute, deleting or creating the parent or the relation linkage will trigger a CASCADE delete or create to the relation entity itself.
-     * For weak affinity mode on a relation attribute, deleting or creating the parent or the relation linkage will NOT trigger a CASCADE delete or create to the relation entity itself.
-     */
+    /** Deleting or creating the parent or the linkage does NOT cascade to the relation entity. */
     RelationAffinityMode["WEAK"] = "weak";
+    /** Deleting or creating the parent or the linkage cascades to the relation entity. */
     RelationAffinityMode["STRONG"] = "strong";
 })(RelationAffinityMode = exports.RelationAffinityMode || (exports.RelationAffinityMode = {}));
+/** Types that point at another entity. A repeatable relation is still a relation. */
+exports.RELATION_ATTRIBUTE_TYPE_LIST = [
+    'relation',
+    'relation_user',
+    'relation_address',
+    'relation_payment_method',
+];
+/** `string`, not `AttributeType`, so callers can test an unnarrowed `attribute.type`. */
+exports.RELATION_ATTRIBUTE_TYPES = new Set(exports.RELATION_ATTRIBUTE_TYPE_LIST);
+/**
+ * Entity attribute types a conditional pricing variant may override (`overridable_attribute`).
+ * An allowlist, so a new scalar type is never overridable by default; a new relation type is, since
+ * relations are overridable by kind. No pricing schema to `satisfies` against — `models.test.ts`
+ * checks these against the entity spec.
+ *
+ * Scalars are overridden value for value. The relation types are overridden as a whole: the
+ * variant's `$relation` list replaces the base entity's, which is how a variant swaps a product's
+ * prices or a composite price's components. They are spread from `RELATION_ATTRIBUTE_TYPE_LIST`
+ * above rather than restated, so the two sets cannot drift.
+ */
+exports.OVERRIDABLE_ATTRIBUTE_TYPE_LIST = __spreadArray([
+    'string',
+    'number',
+    'currency',
+    'boolean',
+    'date',
+    'datetime',
+    'select',
+    'radio',
+    'multiselect',
+    'checkbox',
+    'country',
+    'tags'
+], exports.RELATION_ATTRIBUTE_TYPE_LIST, true);
+/** `string`, not a literal union, so callers can test an unnarrowed `attribute.type`. */
+exports.OVERRIDABLE_ATTRIBUTE_TYPES = new Set(exports.OVERRIDABLE_ATTRIBUTE_TYPE_LIST);
 //# sourceMappingURL=schema-model.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/entity-client",
-  "version": "7.4.0",
+  "version": "7.5.2",
   "description": "JavaScript client library for the epilot Core Entity API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +28,7 @@
     "prepublishOnly": "npm run typegen && npm run build",
     "openapi": "node ../../scripts/update-openapi.js https://docs.api.epilot.io/entity.yaml",
     "typegen": "openapi typegen src/openapi.json --client > src/openapi.d.ts",
+    "openapi:local": "node ../../scripts/update-openapi.js ../../../entity-api/lambda/ApiHandlerFunction/openapi.yml",
     "build": "tsc && npm run build:patch && npm run bundle-definition",
     "build:patch": "sed -i'' -e '/^__exportStar.*openapi.*$/d' dist/index.js",
     "build:watch": "npm run build && tsc -w",