@retailcrm/embed-ui-v1-endpoint 0.9.21 → 0.9.22-alpha.1

package/docs/targets/order-mg-delivery-after.yml

@@ -0,0 +1,51 @@
+target: "order/mg:delivery.after"
+summary: >
+  Widget for the block "Delivery". It is placed in the chat order form: Section end, right under the input fields.
+language: en-GB
+audience: ai
+
+public_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/common"
+  named:
+    - targets
+    - TargetName
+
+runner_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/remote/widgets"
+  named:
+    - defineWidgetRunner
+    - defineMultiRunner
+
+page:
+  id: "order/mg"
+  label: "chat order form"
+  area: "delivery.after"
+
+description: "Widget for the block \"Delivery\""
+location: "Section end, right under the input fields"
+
+target_config:
+  contexts:
+    - "order/card"
+    - "order/card:settings"
+    - "user/current"
+    - "settings"
+  custom_contexts:
+    - "order"
+  action_scopes:
+    - "order/card"
+
+use_when:
+  - "Place a widget exactly at order/mg:delivery.after."
+  - "The widget belongs to the chat order form and should appear at this location: Section end, right under the input fields."
+  - "The widget can work with the contexts listed in target_config.contexts."
+
+avoid_when:
+  - "The widget belongs to a different page, section, or field-level insertion point."
+  - "The widget requires contexts, custom contexts, or action scopes that are not listed in target_config."
+
+ai_notes:
+  - "Use the target id as the runner registration key."
+  - "Use targets[target].contexts as the source of truth for context availability."
+  - "Do not duplicate target context lists in generated widget code."
+  - "Order card and chat order form targets share the same order form data contract."

package/docs/targets/order-mg-delivery-before.yml

@@ -0,0 +1,51 @@
+target: "order/mg:delivery.before"
+summary: >
+  Widget for the block "Delivery". It is placed in the chat order form: Section start, right above the input field.
+language: en-GB
+audience: ai
+
+public_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/common"
+  named:
+    - targets
+    - TargetName
+
+runner_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/remote/widgets"
+  named:
+    - defineWidgetRunner
+    - defineMultiRunner
+
+page:
+  id: "order/mg"
+  label: "chat order form"
+  area: "delivery.before"
+
+description: "Widget for the block \"Delivery\""
+location: "Section start, right above the input field"
+
+target_config:
+  contexts:
+    - "order/card"
+    - "order/card:settings"
+    - "user/current"
+    - "settings"
+  custom_contexts:
+    - "order"
+  action_scopes:
+    - "order/card"
+
+use_when:
+  - "Place a widget exactly at order/mg:delivery.before."
+  - "The widget belongs to the chat order form and should appear at this location: Section start, right above the input field."
+  - "The widget can work with the contexts listed in target_config.contexts."
+
+avoid_when:
+  - "The widget belongs to a different page, section, or field-level insertion point."
+  - "The widget requires contexts, custom contexts, or action scopes that are not listed in target_config."
+
+ai_notes:
+  - "Use the target id as the runner registration key."
+  - "Use targets[target].contexts as the source of truth for context availability."
+  - "Do not duplicate target context lists in generated widget code."
+  - "Order card and chat order form targets share the same order form data contract."

package/docs/targets/order-mg-list-after.yml

@@ -0,0 +1,51 @@
+target: "order/mg:list.after"
+summary: >
+  Widget for the block "Order items". It is placed in the chat order form: Section end, right after the list of order items and before the discount, privilege selection, etc. input fields.
+language: en-GB
+audience: ai
+
+public_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/common"
+  named:
+    - targets
+    - TargetName
+
+runner_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/remote/widgets"
+  named:
+    - defineWidgetRunner
+    - defineMultiRunner
+
+page:
+  id: "order/mg"
+  label: "chat order form"
+  area: "list.after"
+
+description: "Widget for the block \"Order items\""
+location: "Section end, right after the list of order items and before the discount, privilege selection, etc. input fields"
+
+target_config:
+  contexts:
+    - "order/card"
+    - "order/card:settings"
+    - "user/current"
+    - "settings"
+  custom_contexts:
+    - "order"
+  action_scopes:
+    - "order/card"
+
+use_when:
+  - "Place a widget exactly at order/mg:list.after."
+  - "The widget belongs to the chat order form and should appear at this location: Section end, right after the list of order items and before the discount, privilege selection, etc. input fields."
+  - "The widget can work with the contexts listed in target_config.contexts."
+
+avoid_when:
+  - "The widget belongs to a different page, section, or field-level insertion point."
+  - "The widget requires contexts, custom contexts, or action scopes that are not listed in target_config."
+
+ai_notes:
+  - "Use the target id as the runner registration key."
+  - "Use targets[target].contexts as the source of truth for context availability."
+  - "Do not duplicate target context lists in generated widget code."
+  - "Order card and chat order form targets share the same order form data contract."

package/docs/targets/order-mg-list-before.yml

@@ -0,0 +1,51 @@
+target: "order/mg:list.before"
+summary: >
+  Widget for the block "Order items". It is placed in the chat order form: Section start, right above the list of order items.
+language: en-GB
+audience: ai
+
+public_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/common"
+  named:
+    - targets
+    - TargetName
+
+runner_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/remote/widgets"
+  named:
+    - defineWidgetRunner
+    - defineMultiRunner
+
+page:
+  id: "order/mg"
+  label: "chat order form"
+  area: "list.before"
+
+description: "Widget for the block \"Order items\""
+location: "Section start, right above the list of order items"
+
+target_config:
+  contexts:
+    - "order/card"
+    - "order/card:settings"
+    - "user/current"
+    - "settings"
+  custom_contexts:
+    - "order"
+  action_scopes:
+    - "order/card"
+
+use_when:
+  - "Place a widget exactly at order/mg:list.before."
+  - "The widget belongs to the chat order form and should appear at this location: Section start, right above the list of order items."
+  - "The widget can work with the contexts listed in target_config.contexts."
+
+avoid_when:
+  - "The widget belongs to a different page, section, or field-level insertion point."
+  - "The widget requires contexts, custom contexts, or action scopes that are not listed in target_config."
+
+ai_notes:
+  - "Use the target id as the runner registration key."
+  - "Use targets[target].contexts as the source of truth for context availability."
+  - "Do not duplicate target context lists in generated widget code."
+  - "Order card and chat order form targets share the same order form data contract."

package/docs/targets/order-mg-payment-after.yml

@@ -0,0 +1,51 @@
+target: "order/mg:payment.after"
+summary: >
+  Widget for the block "Payment". It is placed in the chat order form: Section end, after the list of payments, controls, and custom fields.
+language: en-GB
+audience: ai
+
+public_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/common"
+  named:
+    - targets
+    - TargetName
+
+runner_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/remote/widgets"
+  named:
+    - defineWidgetRunner
+    - defineMultiRunner
+
+page:
+  id: "order/mg"
+  label: "chat order form"
+  area: "payment.after"
+
+description: "Widget for the block \"Payment\""
+location: "Section end, after the list of payments, controls, and custom fields"
+
+target_config:
+  contexts:
+    - "order/card"
+    - "order/card:settings"
+    - "user/current"
+    - "settings"
+  custom_contexts:
+    - "order"
+  action_scopes:
+    - "order/card"
+
+use_when:
+  - "Place a widget exactly at order/mg:payment.after."
+  - "The widget belongs to the chat order form and should appear at this location: Section end, after the list of payments, controls, and custom fields."
+  - "The widget can work with the contexts listed in target_config.contexts."
+
+avoid_when:
+  - "The widget belongs to a different page, section, or field-level insertion point."
+  - "The widget requires contexts, custom contexts, or action scopes that are not listed in target_config."
+
+ai_notes:
+  - "Use the target id as the runner registration key."
+  - "Use targets[target].contexts as the source of truth for context availability."
+  - "Do not duplicate target context lists in generated widget code."
+  - "Order card and chat order form targets share the same order form data contract."

package/docs/targets/order-mg-payment-before.yml

@@ -0,0 +1,51 @@
+target: "order/mg:payment.before"
+summary: >
+  Widget for the block "Payment". It is placed in the chat order form: Section start, right above the input field.
+language: en-GB
+audience: ai
+
+public_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/common"
+  named:
+    - targets
+    - TargetName
+
+runner_import:
+  from: "@retailcrm/embed-ui-v1-endpoint/remote/widgets"
+  named:
+    - defineWidgetRunner
+    - defineMultiRunner
+
+page:
+  id: "order/mg"
+  label: "chat order form"
+  area: "payment.before"
+
+description: "Widget for the block \"Payment\""
+location: "Section start, right above the input field"
+
+target_config:
+  contexts:
+    - "order/card"
+    - "order/card:settings"
+    - "user/current"
+    - "settings"
+  custom_contexts:
+    - "order"
+  action_scopes:
+    - "order/card"
+
+use_when:
+  - "Place a widget exactly at order/mg:payment.before."
+  - "The widget belongs to the chat order form and should appear at this location: Section start, right above the input field."
+  - "The widget can work with the contexts listed in target_config.contexts."
+
+avoid_when:
+  - "The widget belongs to a different page, section, or field-level insertion point."
+  - "The widget requires contexts, custom contexts, or action scopes that are not listed in target_config."
+
+ai_notes:
+  - "Use the target id as the runner registration key."
+  - "Use targets[target].contexts as the source of truth for context availability."
+  - "Do not duplicate target context lists in generated widget code."
+  - "Order card and chat order form targets share the same order form data contract."

package/docs/targets.md

@@ -7,12 +7,14 @@
 
 - `targets` — словарь встроенных target-конфигураций.
 - `TargetName` — union всех ключей `targets`.
-- `defineTarget(id, contexts)` — helper для объявления target с типами контекстов.
+- `TargetList` — словарь `target -> SchemaList`, выведенный из `targets[target].contexts`.
+- `defineTarget(id, config)` — helper для объявления target с типами контекстов, custom contexts и action scopes.
+  Также поддерживает альтернативную форму `defineTarget(id, contexts)`.
 
 ## Что такое `target` и `context`
 
 `target` — это идентификатор места встраивания виджета в интерфейсе CRM. Он отвечает на вопрос:
-«куда CRM сейчас монтирует remote-виджет?». Например, `order/card:common.before` означает конкретную
+«куда CRM сейчас монтирует встраиваемый виджет?». Например, `order/card:common.before` означает конкретную
 точку встраивания на карточке заказа.
 
 `context` — это набор реактивных данных, доступных виджету в этом месте. Он отвечает на вопрос:
@@ -22,15 +24,6 @@
 `target` не является данными заказа, клиента или пользователя. Это только место встраивания.
 Данные нужно брать из контекстов, которые привязаны к этому `target`.
 
-## Примеры встроенных `target`
-
-| Target | Где встраивается | Доступные контексты |
-| --- | --- | --- |
-| `order/card:common.before` | Карточка заказа, перед блоком общей информации | `order/card`, `user/current`, `settings` |
-| `order/card:customer.phone` | Карточка заказа, поле телефона клиента | `order/card`, `user/current`, `settings` |
-| `customer/card:phone` | Карточка клиента, телефонный блок | `customer/card`, `customer/card:phone`, `user/current`, `settings` |
-| `order/mg:list.before` | Карточка заказа, перед списком в multi-goods блоке | `order/card`, `order/card:settings`, `user/current`, `settings` |
-
 ## Проверка контекстов для `target`
 
 ```ts
@@ -60,6 +53,7 @@ const selectedTarget: TargetName = 'order/card:common.before'
 import type { TargetName } from '@retailcrm/embed-ui-v1-endpoint/common'
 
 import { useContext as useOrderContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card'
+import { useContext as useOrderSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/order/card-settings'
 import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-contexts/remote/settings'
 import { useContext as useUserContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current'
 
@@ -68,13 +62,14 @@ defineProps<{
 }>()
 
 const order = useOrderContext()
+const orderSettings = useOrderSettingsContext()
 const settings = useSettingsContext()
 const user = useUserContext()
 </script>
 ```
 
 Такой набор контекстов подходит для `order/card:common.before`, потому что этот `target` объявлен с
-контекстами `order/card`, `user/current` и `settings`.
+контекстами `order/card`, `order/card:settings`, `user/current` и `settings`.
 
 Для `customer/card:phone` набор импортов будет другим:
 
@@ -85,18 +80,48 @@ import { useContext as useSettingsContext } from '@retailcrm/embed-ui-v1-context
 import { useContext as useUserContext } from '@retailcrm/embed-ui-v1-contexts/remote/user/current'
 ```
 
-## Пример `defineTarget`
+## `defineTarget` в тестах
+
+CRM не предоставляет расширениям механизм регистрации произвольных widget targets.
+В рабочем сценарии виджет монтируется только в заранее определённые платформой цели из `targets`.
+
+`defineTarget` нужен для объявления этих встроенных целей внутри пакета и для автотестов,
+где требуется собрать изолированную target-конфигурацию без запуска CRM.
 
 ```ts
 import { defineTarget } from '@retailcrm/embed-ui-v1-endpoint/common'
 
-const customTarget = defineTarget('order/card:custom.after', [
-  'order/card',
+const testTarget = defineTarget('order/card:test.after', {
+  contexts: [
+    'order/card',
+    'order/card:settings',
+    'user/current',
+    'settings',
+  ],
+  customContexts: ['order'],
+  actions: ['order/card'],
+} as const)
+```
+
+Альтернативная форма с массивом контекстов подходит для target без custom contexts и action scopes.
+В этом случае `customContexts` и `actions` будут пустыми:
+
+```ts
+const testTarget = defineTarget('customer/card:test.after', [
+  'customer/card',
   'user/current',
   'settings',
 ] as const)
 ```
 
+## AI-friendly YAML profiles
+
+Для встроенных целей дополнительно генерируется каталог [`targets/*.yml`](./targets/).
+Эти файлы предназначены для AI-ассистентов: они описывают target на английском, перечисляют
+доступные contexts, custom contexts и action scopes, но не являются отдельным источником truth.
+Обновляйте `targets.ts` и `targets.documentation.ts`, затем запускайте
+`yarn workspace @retailcrm/embed-ui-v1-endpoint run build:docs`.
+
 ## Практический совет
 
 Если раннер маппится по `target`, старайтесь использовать ключи из `TargetName`.
@@ -104,8 +129,8 @@ const customTarget = defineTarget('order/card:custom.after', [
 
 Читайте также:
 
-- [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в remote-компонент.
+- [`defineWidgetRunner`](./define-widget-runner.md) — как `target` попадает в компонент встраиваемого виджета.
 - [`menu-placements`](./menu-placements.md) — чем пункты меню для страниц отличаются от widget `target`.
-- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM route.
+- [`page-routes`](./page-routes.md) — как описывать page `code` и CRM-маршрут.
 - [`CONCEPT`](../../v1-contexts/docs/ru/CONCEPT.md) — общий принцип работы контекстов.
 - [`CUSTOM`](../../v1-contexts/docs/ru/CUSTOM.md) — пользовательский контекст для custom fields.

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@retailcrm/embed-ui-v1-endpoint",
+  "bin": {
+    "embed-ui-v1-endpoint": "./bin/embed-ui-v1-endpoint.mjs",
+    "embed-ui-v1-endpoint-mcp": "./bin/embed-ui-v1-endpoint-mcp.mjs"
+  },
   "type": "module",
-  "version": "0.9.21",
+  "version": "0.9.22-alpha.1",
   "description": "Endpoint API for integrations in RetailCRM",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
@@ -25,6 +29,12 @@
       "require": "./dist/common/targets.cjs",
       "default": "./dist/common/targets.js"
     },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js",
+      "require": "./dist/mcp/server.cjs",
+      "default": "./dist/mcp/server.js"
+    },
     "./remote": {
       "types": "./dist/remote.d.ts",
       "import": "./dist/remote.js",
@@ -54,6 +64,9 @@
       "common/targets": [
         "./dist/common/targets.d.ts"
       ],
+      "mcp": [
+        "./dist/mcp/server.d.ts"
+      ],
       "remote": [
         "./dist/remote.d.ts"
       ],
@@ -66,29 +79,35 @@
     }
   },
   "files": [
+    "bin",
     "dist",
     "docs",
     "README.md"
   ],
   "scripts": {
-    "build": "yarn build:code",
+    "build": "yarn build:docs && yarn build:code && yarn build:mcp && yarn build:meta",
     "build:code": "vite build -c ./vite.config.ts",
+    "build:docs": "npx tsx scripts/build.docs.ts",
+    "build:mcp": "vite build -c ./vite.config.mcp.ts",
+    "build:meta": "npx tsx scripts/build.meta.ts",
     "test:e2e": "yarn exec vitest --run --config ./vitest.config.playwright.ts",
     "test:playwright": "yarn exec vitest --run --config ./vitest.config.playwright.ts",
     "test": "vitest --run"
   },
   "peerDependencies": {
+    "@omnicajs/vue-remote": "^0.2.23",
     "@remote-ui/rpc": "^1.4",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.21",
-    "@retailcrm/embed-ui-v1-types": "^0.9.21",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.22-alpha.1",
+    "@retailcrm/embed-ui-v1-types": "^0.9.22-alpha.1",
     "pinia": "^2.2",
     "vue": "^3.5"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@remote-ui/rpc": "^1.4.7",
-    "@retailcrm/embed-ui-v1-components": "^0.9.21",
-    "@retailcrm/embed-ui-v1-contexts": "^0.9.21",
-    "@retailcrm/embed-ui-v1-types": "^0.9.21"
+    "@retailcrm/embed-ui-v1-components": "^0.9.22-alpha.1",
+    "@retailcrm/embed-ui-v1-contexts": "^0.9.22-alpha.1",
+    "@retailcrm/embed-ui-v1-types": "^0.9.22-alpha.1"
   },
   "devDependencies": {
     "@retailcrm/image-preview": "^1.0.2",
@@ -97,6 +116,7 @@
     "date-fns": "^4.1.0",
     "lodash.isequal": "^4.5.0",
     "playwright": "1.58.2",
+    "tsx": "^4.21.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "4.1.3"