RUEN

Документация

От первого блока до подключённого модуля

Короткая документация по реальному Buywell: сначала работа со сценариями, затем контракт для разработчиков модулей.
Для пользователя

Соберите и запустите сценарий

Основные понятия

Сценарий — версионируемый граф действий и условий. Блок выполняет один шаг. Адаптер вызывает конкретный внешний API силами Buywell. Модуль связывает Buywell с площадкой и поставляет собственные события и блоки.

  • Черновик можно менять и тестировать.
  • Опубликованная версия неизменна.
  • Подключение связывает опубликованный сценарий с событием точной версии модуля.

Первый сценарий

01ЧерновикСоберите граф
02ПроверкаИсправьте ошибки
03ПубликацияЗафиксируйте ревизию
04ПодключениеВыберите событие
05ЗапускПроверьте журнал

Новый сценарий начинается с блока «Запуск». Добавьте действия и условия из левой панели, соедините их и завершите каждый путь успешным или неуспешным результатом.

Входы сценария задаются отдельно. Значение поля можно ввести вручную, взять из входа сценария или из результата предыдущего шага.

  • Дайте сценарию понятное название.
  • Настройте обязательные поля каждого блока.
  • Проведите все ветки до блока завершения.

Проверка и публикация

Проверка сценария показывает ошибки структуры и несовместимости. Тестовый запуск использует введённые вами данные и выводит упорядоченный результат каждого шага.

Публикация фиксирует точную ревизию. Следующие правки остаются в новом черновике, а возврат к старой опубликованной версии выполняется через историю.

  • Исправьте ошибки из единой области диагностики.
  • Проверьте успешную и альтернативные ветки.
  • Публикуйте только после теста.

События и подключения

После публикации выберите событие установленного модуля. Buywell покажет только объявленные модулем условия запуска и доступные источники данных.

Совместимость проверяется до включения: версия пакета, событие, используемые блоки и подключённый Edge-драйвер должны совпадать.

  • Условия запуска фильтруют события.
  • Поля данных заполняют входы сценария.
  • Подключение включается только после успешной проверки.

История запусков

История показывает итог запуска, шаги, длительность и понятное место остановки. При временной ошибке применяется объявленная политика повторов; постоянная ошибка завершает запуск и остаётся в журнале.

  • Проверьте вход и результат остановившегося шага.
  • Убедитесь, что нужная версия модуля подключена.
  • Не передавайте пароли и ключи в обычные поля сценария.
Для разработчика

Создайте модуль для Buywell

Пакет модуля

ОДИН НЕИЗМЕНЯЕМЫЙ АРХИВmodule-name.buywell-module.zipВерсия + содержимое = идентичность пакета
manifest.jsonконтракт и относительные пути
edge/driver.pyEdge-драйвер
guides/install.ru.mdобязательная инструкция
guides/install.en.mdопциональный перевод
assets/icon.pngопциональный локальный asset
✓ Buywell проверяет файлы✓ Buywell рассчитывает digest× URL драйвера не нужен× Ручные hashes не нужны

Модуль распространяется как один ZIP-файл с расширением .buywell-module.zip. Внутри находятся manifest.json, один Edge-драйвер, обязательная русская Markdown-инструкция, опциональные локализованные README и changelog, а также локальные assets.

  • Пути в manifest.json относительны архиву.
  • URL драйвера и вручную рассчитанные hashes не нужны.
  • Версия и содержимое опубликованного пакета неизменны.

Спецификация manifest.json

Manifest — строгий версионируемый контракт пакета. Он объявляет идентичность модуля, файлы архива, события, доступные данные, блоки и реализации нейтральных действий.

В Edge-пакете модуль сам задаёт русское и английское название каждого поля настройки через configuration_field; Edge не угадывает смысл поля по его имени.

Скопируйте минимальный валидный пример, затем сверяйте каждое поле со справочником. Неизвестные поля запрещены, а связанные пути, типы, namespace и версии проверяются вместе.

СПЕЦИФИКАЦИЯ MANIFEST

Всё, что может объявить manifest.json

Каждый пример на этой странице проверяется тем же контрактом, который используется при установке пакета. Начните с компактного примера, а затем сверяйте события, источники данных, блоки и правила совместимости со справочником полей.

Для Buywell Edge Python SDK генерирует Manifest v2, схемы, список файлов, digest и подпись из типизированных деклараций. Подписанный adapter-driver сам поставляет управляемый адаптер и поля операций при подключении Edge; Buywell проверяет подпись до показа пользовательских блоков. Существующие модули могут сохранить весь manifest v1 как контракт совместимости.

ВАЛИДНЫЙ ПРИМЕР ДЛЯ КОПИРОВАНИЯJSON
{
  "schemaVersion": 1,
  "protocolVersion": "1.0.0",
  "module": {
    "id": "example.delivery",
    "version": "1.0.0",
    "displayName": "Example Delivery",
    "description": "A minimal module package example.",
    "publisher": "Example developer",
    "supportedPlatforms": [
      "Example Platform"
    ]
  },
  "nodes": [
    {
      "type": "example.delivery/send-message",
      "version": "1.0.0",
      "kind": "action",
      "displayName": "Send message",
      "localization": {
        "ru": {
          "displayName": "Отправить сообщение"
        },
        "en": {
          "displayName": "Send message"
        }
      },
      "inputSchema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "additionalProperties": false
      },
      "outputSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      },
      "configSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      },
      "requiredEventContext": [
        {
          "eventType": "commerce.purchase.created",
          "eventVersion": "1.0.0",
          "source": "scope",
          "path": "conversationId"
        }
      ],
      "ui": {
        "category": "Messages",
        "icon": "message"
      }
    }
  ],
  "events": [
    {
      "type": "commerce.purchase.created",
      "version": "1.0.0",
      "displayName": "Purchase received",
      "localization": {
        "ru": {
          "displayName": "Получена покупка"
        },
        "en": {
          "displayName": "Purchase received"
        }
      },
      "payloadSchema": {
        "type": "object",
        "properties": {
          "purchaseId": {
            "type": "string"
          },
          "recipient": {
            "type": "string"
          }
        },
        "required": [
          "purchaseId",
          "recipient"
        ],
        "additionalProperties": false
      },
      "scopeSchema": {
        "type": "object",
        "properties": {
          "conversationId": {
            "type": "string"
          }
        },
        "required": [
          "conversationId"
        ],
        "additionalProperties": false
      },
      "selectors": [],
      "bindingFields": [
        {
          "id": "recipient",
          "source": "payload",
          "path": "recipient",
          "valueSchema": {
            "type": "string"
          },
          "displayName": "Recipient",
          "localization": {
            "ru": {
              "displayName": "Получатель"
            },
            "en": {
              "displayName": "Recipient"
            }
          },
          "recommended": true,
          "availability": "always"
        }
      ],
      "identityFields": [
        "purchaseId"
      ],
      "ui": {
        "category": "Sales",
        "icon": "cart"
      }
    }
  ],
  "abstractions": [
    {
      "abstractionId": "messaging.send-in-context",
      "abstractionVersion": "1.0.0",
      "nodeType": "example.delivery/send-message",
      "nodeVersion": "1.0.0"
    }
  ],
  "package": {
    "branding": {
      "icon": "assets/icon.png"
    },
    "artifact": {
      "path": "edge/driver.py",
      "filename": "driver.py"
    },
    "guides": {
      "installation": {
        "ru": "guides/install.ru.md",
        "en": "guides/install.en.md"
      },
      "readme": {
        "ru": "guides/README.ru.md",
        "en": "guides/README.en.md"
      },
      "changelog": {
        "ru": "guides/CHANGELOG.ru.md",
        "en": "guides/CHANGELOG.en.md"
      }
    },
    "compatibility": {
      "environments": [
        "Example Runtime 1.x"
      ]
    },
    "release": {
      "critical": false
    }
  }
}
СПРАВОЧНИК ПОЛЕЙ MANIFEST

За что отвечает каждое поле и какие значения принимает

Корень manifest7 полей

Идентичность пакета, его содержимое и публичные возможности.

schemaVersion1обязательное поле

Можно опустить: при разборе и в каноническом manifest становится 1. · по умолчанию: 1

protocolVersion"1.0.0"обязательное поле

Можно опустить: при разборе и в каноническом manifest становится 1.0.0. · по умолчанию: "1.0.0"

moduleobjectобязательное поле

Идентичность, издатель и поддерживаемые площадки. · лишние поля запрещены

nodesarrayобязательное поле

Блоки, принадлежащие пакету. · максимум элементов: 100

eventsarray

Версионируемые события модуля. · максимум элементов: 100

abstractionsarray

Реализации платформенно-нейтральных контрактов. · максимум элементов: 100

packageobject

Файлы архива, совместимость и сведения о релизе. · лишние поля запрещены

module10 полей

Назначение, допустимые значения и ограничения этой части manifest.

module.idstringобязательное поле

Строчные сегменты через точку или дефис, например example.delivery. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

module.versionstringобязательное поле

Формат x.y.z с опциональным prerelease. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

module.displayNamestringобязательное поле

Основное название; localization может заменить его в RU/EN. · минимальная длина: 1 · максимальная длина: 120

module.descriptionstring

Краткое пользовательское описание. · максимальная длина: 2000

module.publisherstringобязательное поле

Имя издателя пакета. · минимальная длина: 1 · максимальная длина: 160

module.supportedPlatformsarrayобязательное поле

Человекочитаемые названия поддерживаемых площадок. · минимум элементов: 1 · максимум элементов: 50

module.documentationobject

Опциональные HTTPS/HTTP homepageUrl, supportUrl и sourceUrl. · лишние поля запрещены

module.documentation.homepageUrlstring

Ссылка на страницу модуля или его издателя. · максимальная длина: 2048 · format: uri

module.documentation.supportUrlstring

Ссылка, по которой пользователь может получить поддержку модуля. · максимальная длина: 2048 · format: uri

module.documentation.sourceUrlstring

Ссылка на исходный код модуля, если издатель его публикует. · максимальная длина: 2048 · format: uri

nodes[]31 полей

Назначение, допустимые значения и ограничения этой части manifest.

nodes[].typestringобязательное поле

Обязан начинаться с точного namespace module.id/. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z][a-z0-9.-]*$

nodes[].versionstringобязательное поле

Версия контракта блока. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

nodes[].kind"action" | "condition"обязательное поле

Condition требует branches; action запрещает branches.

nodes[].displayNamestringобязательное поле

displayName обязателен; description и RU/EN localization опциональны. · минимальная длина: 1 · максимальная длина: 120

nodes[].descriptionstring

displayName обязателен; description и RU/EN localization опциональны. · максимальная длина: 2000

nodes[].localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

nodes[].localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

nodes[].localization.ru.displayNamestring

displayName обязателен; description и RU/EN localization опциональны. · минимальная длина: 1 · максимальная длина: 120

nodes[].localization.ru.descriptionstring

displayName обязателен; description и RU/EN localization опциональны. · максимальная длина: 2000

nodes[].localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

nodes[].localization.en.displayNamestring

displayName обязателен; description и RU/EN localization опциональны. · минимальная длина: 1 · максимальная длина: 120

nodes[].localization.en.descriptionstring

displayName обязателен; description и RU/EN localization опциональны. · максимальная длина: 2000

nodes[].inputSchemavalueобязательное поле

Входы действия или условия.

nodes[].outputSchemavalueобязательное поле

По умолчанию закрытые пустые объекты. · по умолчанию: {"type":"object","properties":{},"required":[],"additionalProperties":false}

nodes[].configSchemavalueобязательное поле

По умолчанию закрытые пустые объекты. · по умолчанию: {"type":"object","properties":{},"required":[],"additionalProperties":false}

nodes[].requiredEventContextarray

Существующие eventType@version и payload/scope paths. · максимум элементов: 100

nodes[].requiredEventContext[].eventTypestringобязательное поле

Указывает событие, контекст которого необходим блоку для выполнения. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

nodes[].requiredEventContext[].eventVersionstringобязательное поле

Закрепляет точную версию требуемого события. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

nodes[].requiredEventContext[].source"payload" | "scope"обязательное поле

Путь обязан существовать в соответствующей схеме.

nodes[].requiredEventContext[].pathstringобязательное поле

Единственный Edge-драйвер внутри архива. · минимальная длина: 1 · максимальная длина: 512

nodes[].branchesarray

Только для condition; каждая ветка содержит id и label. · минимум элементов: 2 · максимум элементов: 20

nodes[].branches[].idstringобязательное поле

Строчные сегменты через точку или дефис, например example.delivery. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

nodes[].branches[].labelstringобязательное поле

Человекочитаемое название выхода блока-условия в редакторе. · минимальная длина: 1 · максимальная длина: 120

nodes[].retryPolicyobject

maxAttempts, initialBackoffMs и maxBackoffMs в допустимых пределах. · лишние поля запрещены

nodes[].retryPolicy.maxAttemptsintegerобязательное поле

Ограничивает общее число попыток выполнения блока. · ≥ 1 · ≤ 10

nodes[].retryPolicy.initialBackoffMsintegerобязательное поле

Задаёт паузу перед первой повторной попыткой блока. · ≥ 0 · ≤ 300000

nodes[].retryPolicy.maxBackoffMsintegerобязательное поле

Ограничивает максимальную паузу между повторными попытками блока. · ≥ 0 · ≤ 3600000

nodes[].uiobjectобязательное поле

category, #RRGGBB color и icon. · по умолчанию: {"category":"Other"} · лишние поля запрещены

nodes[].ui.categorystringобязательное поле

Определяет раздел библиотеки блоков, в котором показывается блок. · по умолчанию: "Other" · минимальная длина: 1 · максимальная длина: 80

nodes[].ui.colorstring

Задаёт акцентный цвет блока в редакторе. · формат: ^#[0-9A-Fa-f]{6}$

nodes[].ui.iconstring

PNG, JPEG или WebP с совпадающим расширением. · минимальная длина: 1 · максимальная длина: 80

events[]106 полей

Назначение, допустимые значения и ограничения этой части manifest.

events[].typestringобязательное поле

Версионируемая идентичность события. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

events[].versionstringобязательное поле

Версионируемая идентичность события. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

events[].displayNamestringобязательное поле

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

events[].localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

events[].localization.ru.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].localization.ru.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

events[].localization.en.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].localization.en.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].payloadSchemavalueобязательное поле

Тело события; каждый identityFields path обязан существовать и быть required.

events[].scopeSchemavalueобязательное поле

Контекст выполнения. По умолчанию закрытый пустой объект. · по умолчанию: {"type":"object","properties":{},"required":[],"additionalProperties":false}

events[].selectorsarrayобязательное поле

Поля фильтра запуска; по умолчанию []. · по умолчанию: [] · максимум элементов: 100

events[].selectors[].idstringобязательное поле

Строчные сегменты через точку или дефис, например example.delivery. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].selectors[].displayNamestringобязательное поле

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].selectors[].source"payload" | "scope"обязательное поле

Путь обязан существовать в соответствующей схеме.

events[].selectors[].pathstringобязательное поле

Единственный Edge-драйвер внутри архива. · минимальная длина: 1 · максимальная длина: 512

events[].selectors[].operatorsarrayобязательное поле

exists, equals, not-equals, in, contains, starts-with, ends-with или matches. · минимум элементов: 1 · максимум элементов: 8

events[].selectors[].localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

events[].selectors[].localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

events[].selectors[].localization.ru.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].selectors[].localization.ru.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].selectors[].localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

events[].selectors[].localization.en.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].selectors[].localization.en.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingFieldsarray

Типизированные payload/scope значения, доступные как источники входов. · максимум элементов: 200

events[].bindingFields[].idstringобязательное поле

Строчные сегменты через точку или дефис, например example.delivery. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].bindingFields[].source"payload" | "scope"обязательное поле

Путь обязан существовать в соответствующей схеме.

events[].bindingFields[].pathstringобязательное поле

Единственный Edge-драйвер внутри архива. · минимальная длина: 1 · максимальная длина: 512

events[].bindingFields[].valueSchemavalueобязательное поле

Тип должен совпадать с типом объявленного пути.

events[].bindingFields[].displayNamestringобязательное поле

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingFields[].descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingFields[].localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

events[].bindingFields[].localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

events[].bindingFields[].localization.ru.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingFields[].localization.ru.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingFields[].localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

events[].bindingFields[].localization.en.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingFields[].localization.en.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingFields[].categorystring

Группирует доступное значение в выборе источника данных. · минимальная длина: 1 · максимальная длина: 80

events[].bindingFields[].orderinteger

Определяет порядок значения среди других доступных данных события. · ≥ 0 · ≤ 10000

events[].bindingFields[].recommendedboolean

Подсказки UI и правила обращения с данными.

events[].bindingFields[].nullableboolean

Подсказки UI и правила обращения с данными.

events[].bindingFields[].availability"always" | "when-present"обязательное поле

По умолчанию always. · по умолчанию: "always"

events[].bindingFields[].sensitiveboolean

Подсказки UI и правила обращения с данными.

events[].bindingFields[].keyedobject

Для объектного path объявляет guardPath и guardParameter параметризованного строкового значения. · лишние поля запрещены

events[].bindingFields[].keyed.guardPathstringобязательное поле

Проверяет контекст перед чтением параметризованного ключа объектного поля. · минимальная длина: 1 · максимальная длина: 512

events[].bindingFields[].keyed.guardParameterstringобязательное поле

Называет параметр биндинга, значение которого должно совпасть с guardPath. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].bindingCatalogsarray

Объявляет каталоги категорий, товаров или других областей, из которых пользователь может выбрать контекст события. · максимум элементов: 20

events[].bindingCatalogs[].idstringобязательное поле

Строчные сегменты через точку или дефис, например example.delivery. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

events[].bindingCatalogs[].versionstringобязательное поле

Версионируемая идентичность события. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

events[].bindingCatalogs[].displayNamestringобязательное поле

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingCatalogs[].localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

events[].bindingCatalogs[].localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

events[].bindingCatalogs[].localization.ru.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingCatalogs[].localization.ru.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingCatalogs[].localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

events[].bindingCatalogs[].localization.en.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingCatalogs[].localization.en.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingCatalogs[].scopeobjectобязательное поле

Описывает селектор и параметр, которые связывают выбор из каталога с контекстом события. · лишние поля запрещены

events[].bindingCatalogs[].scope.displayNamestringобязательное поле

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingCatalogs[].scope.localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

events[].bindingCatalogs[].scope.localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

events[].bindingCatalogs[].scope.localization.ru.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingCatalogs[].scope.localization.ru.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingCatalogs[].scope.localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

events[].bindingCatalogs[].scope.localization.en.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].bindingCatalogs[].scope.localization.en.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].bindingCatalogs[].scope.selectorIdstringобязательное поле

Ссылается на селектор события с оператором equals, который ограничивает выбранную область. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].bindingCatalogs[].scope.guardParameterstringобязательное поле

Называет параметр, которым выбранное значение каталога передаётся в keyed-поля. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].bindingCatalogs[].valueFieldIdstringобязательное поле

Ссылается на keyed-поле, содержащее внутреннее значение элемента каталога. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].bindingCatalogs[].choiceFieldIdstringобязательное поле

Ссылается на keyed-поле, содержащее отображаемый пользователю вариант каталога. · формат: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$

events[].identityFieldsarrayобязательное поле

Пути payload, образующие идентичность события. · минимум элементов: 1 · максимум элементов: 20

events[].inputResolversarray

Версионируемые immediate/deferred источники данных. · максимум элементов: 50

events[].inputResolvers[].idstringобязательное поле

Строчные сегменты через точку или дефис, например example.delivery. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

events[].inputResolvers[].versionstringобязательное поле

Версионируемая идентичность события. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

events[].inputResolvers[].abstractionIdstring

Опциональная точная абстракция Buywell; оба поля объявляются вместе. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

events[].inputResolvers[].abstractionVersionstring

Опциональная точная абстракция Buywell; оба поля объявляются вместе. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

events[].inputResolvers[].displayNamestringобязательное поле

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].inputResolvers[].descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].inputResolvers[].outputSchemavalueобязательное поле

Точный тип возвращаемого значения.

events[].inputResolvers[].parameterSchemavalue

Для абстракции обязана точно совпадать с её версионированным контрактом.

events[].inputResolvers[].mode"immediate" | "deferred"обязательное поле

Production исполняет deferred; immediate не активируется как удалённая задача.

events[].inputResolvers[].localizationobject

displayName обязателен; description и RU/EN localization опциональны. · лишние поля запрещены

events[].inputResolvers[].localization.ruobject

Непустая UTF-8 Markdown-инструкция. · лишние поля запрещены

events[].inputResolvers[].localization.ru.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].inputResolvers[].localization.ru.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].inputResolvers[].localization.enobject

Опциональный перевод; без него используется RU. · лишние поля запрещены

events[].inputResolvers[].localization.en.displayNamestring

displayName обязателен; description опционален и ограничен 2000 символами. · минимальная длина: 1 · максимальная длина: 120

events[].inputResolvers[].localization.en.descriptionstring

displayName обязателен; description опционален и ограничен 2000 символами. · максимальная длина: 2000

events[].inputResolvers[].requiredContextarray

Каждый payload/scope path существует и гарантирован required. · максимум элементов: 50

events[].inputResolvers[].requiredContext[].source"payload" | "scope"обязательное поле

Путь обязан существовать в соответствующей схеме.

events[].inputResolvers[].requiredContext[].pathstringобязательное поле

Единственный Edge-драйвер внутри архива. · минимальная длина: 1 · максимальная длина: 512

events[].inputResolvers[].timeoutMsinteger

Опциональный лимит ожидания. · ≥ 100 · ≤ 300000

events[].inputResolvers[].retryobject

maxAttempts 1…10 и initialBackoffMs 0…300000. · лишние поля запрещены

events[].inputResolvers[].retry.maxAttemptsintegerобязательное поле

Ограничивает число попыток получить отложенные данные. · ≥ 1 · ≤ 10

events[].inputResolvers[].retry.initialBackoffMsintegerобязательное поле

Задаёт паузу перед повторным получением отложенных данных. · ≥ 0 · ≤ 300000

events[].inputResolvers[].sensitiveboolean

Подсказки UI и правила обращения с данными.

events[].inputResolvers[].uiobject

category по умолчанию Other; icon опционален. · лишние поля запрещены

events[].inputResolvers[].ui.categorystring

Группирует источник данных в интерфейсе редактора. · минимальная длина: 1 · максимальная длина: 80

events[].inputResolvers[].ui.orderinteger

Определяет порядок источника данных в интерфейсе. · ≥ 0 · ≤ 10000

events[].inputResolvers[].ui.recommendedboolean

Подсказки UI и правила обращения с данными.

events[].uiobjectобязательное поле

category по умолчанию Other; icon опционален. · по умолчанию: {"category":"Other"} · лишние поля запрещены

events[].ui.categorystringобязательное поле

Определяет раздел, в котором событие показывается при выборе запуска. · по умолчанию: "Other" · минимальная длина: 1 · максимальная длина: 80

events[].ui.iconstring

PNG, JPEG или WebP с совпадающим расширением. · минимальная длина: 1 · максимальная длина: 80

abstractions[]4 полей

Назначение, допустимые значения и ограничения этой части manifest.

abstractions[].abstractionIdstringобязательное поле

Указывает стабильный идентификатор нейтрального действия, которое реализует модуль. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)+$

abstractions[].abstractionVersionstringобязательное поле

Закрепляет точную версию контракта выбранного нейтрального действия. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

abstractions[].nodeTypestringобязательное поле

Ссылка на существующий блок этого же module.id. · формат: ^[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z][a-z0-9.-]*$

abstractions[].nodeVersionstringобязательное поле

Ссылка на существующий блок этого же module.id. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

package25 полей

Назначение, допустимые значения и ограничения этой части manifest.

package.brandingobject

Описывает визуальные материалы модуля, поставляемые внутри архива. · лишние поля запрещены

package.branding.iconstringобязательное поле

PNG, JPEG или WebP с совпадающим расширением. · минимальная длина: 1 · максимальная длина: 240

package.artifactobjectобязательное поле

Указывает исполняемый Edge-драйвер этой версии модуля. · лишние поля запрещены

package.artifact.pathstringобязательное поле

Единственный Edge-драйвер внутри архива. · минимальная длина: 1 · максимальная длина: 240

package.artifact.filenamestring

Имя файла для скачивания; не является URL. · минимальная длина: 1 · максимальная длина: 180

package.guidesobjectобязательное поле

Собирает инструкции по установке и дальнейшему обслуживанию модуля. · лишние поля запрещены

package.guides.installationobjectобязательное поле

Содержит обязательную русскую инструкцию установки и опциональный английский перевод. · лишние поля запрещены

package.guides.installation.rustringобязательное поле

Непустая UTF-8 Markdown-инструкция. · минимальная длина: 1 · максимальная длина: 240

package.guides.installation.enstring

Опциональный перевод; без него используется RU. · минимальная длина: 1 · максимальная длина: 240

package.guides.readmeobject

Содержит локализованное описание возможностей модуля для раздела «О модуле». · лишние поля запрещены

package.guides.readme.rustringобязательное поле

Указывает обязательный русский Markdown-файл описания, когда readme объявлен. · минимальная длина: 1 · максимальная длина: 240

package.guides.readme.enstring

Указывает опциональный английский перевод readme; без него используется русский файл. · минимальная длина: 1 · максимальная длина: 240

package.guides.changelogobject

Содержит локализованную историю пользовательских изменений по версиям. · лишние поля запрещены

package.guides.changelog.rustringобязательное поле

Указывает обязательный русский Markdown-файл истории изменений, когда changelog объявлен. · минимальная длина: 1 · максимальная длина: 240

package.guides.changelog.enstring

Указывает опциональный английский перевод changelog; без него используется русский файл. · минимальная длина: 1 · максимальная длина: 240

package.guides.updateUrlstring

Ведёт к инструкции по обновлению модуля. · максимальная длина: 2048 · format: uri

package.guides.rollbackUrlstring

Ведёт к инструкции по возврату на предыдущую версию. · максимальная длина: 2048 · format: uri

package.guides.troubleshootingUrlstring

Ведёт к инструкции по диагностике типичных проблем. · максимальная длина: 2048 · format: uri

package.guides.removalUrlstring

Ведёт к инструкции по безопасному удалению модуля. · максимальная длина: 2048 · format: uri

package.compatibilityobjectобязательное поле

Описывает версии сервиса и окружения, в которых пакет может работать. · лишние поля запрещены

package.compatibility.minimumBuywellVersionstring

Минимальная совместимая версия сервиса. · формат: ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$

package.compatibility.environmentsarrayобязательное поле

Поддерживаемые окружения Buywell Edge. · минимум элементов: 1 · максимум элементов: 30

package.releaseobjectобязательное поле

Содержит сведения о важности релиза и ссылку на список изменений. · по умолчанию: {"critical":false} · лишние поля запрещены

package.release.criticalbooleanобязательное поле

По умолчанию false. · по умолчанию: false

package.release.changelogUrlstring

Опциональная история изменений. · максимальная длина: 2048 · format: uri

ДОСТУПНЫЕ АБСТРАКЦИИ

Нейтральные действия, которые может реализовать модуль

Абстракция позволяет сценарию запросить понятное действие без привязки к одной площадке. Совместимый модуль связывает это действие со своим блоком.

messaging.send-in-context@1.0.0action

Отправить сообщение

Отправить сообщение в текущий диалог.

Блок сценария
abstract/send-in-context@1.0.0
Входы
message*
Известные реализации
example.delivery/send-message@1.0.0
Расширенный нейтральный manifest1 события · 2 блока

Этот пример показывает события, фильтры, данные сценария, резолверы, действия и условия, выполняемые через Buywell Edge.

EXTENDED EXAMPLE / manifest.jsonJSON
{
  "schemaVersion": 1,
  "protocolVersion": "1.0.0",
  "module": {
    "id": "example.delivery",
    "version": "1.1.0",
    "displayName": "Example Delivery",
    "description": "A complete production-compatible manifest example.",
    "publisher": "Example developer",
    "supportedPlatforms": [
      "Example Platform"
    ]
  },
  "nodes": [
    {
      "type": "example.delivery/send-message",
      "version": "1.0.0",
      "kind": "action",
      "displayName": "Send message",
      "localization": {
        "ru": {
          "displayName": "Отправить сообщение"
        },
        "en": {
          "displayName": "Send message"
        }
      },
      "inputSchema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "additionalProperties": false
      },
      "outputSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      },
      "configSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      },
      "requiredEventContext": [
        {
          "eventType": "commerce.purchase.created",
          "eventVersion": "1.0.0",
          "source": "scope",
          "path": "conversationId"
        }
      ],
      "ui": {
        "category": "Messages",
        "icon": "message"
      }
    },
    {
      "type": "example.delivery/has-recipient",
      "version": "1.0.0",
      "kind": "condition",
      "displayName": "Recipient is present",
      "localization": {
        "ru": {
          "displayName": "Получатель указан"
        },
        "en": {
          "displayName": "Recipient is present"
        }
      },
      "inputSchema": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "string"
          }
        },
        "required": [
          "recipient"
        ],
        "additionalProperties": false
      },
      "outputSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      },
      "configSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      },
      "branches": [
        {
          "id": "yes",
          "label": "Yes"
        },
        {
          "id": "no",
          "label": "No"
        }
      ],
      "ui": {
        "category": "Checks",
        "icon": "question"
      }
    }
  ],
  "events": [
    {
      "type": "commerce.purchase.created",
      "version": "1.0.0",
      "displayName": "Purchase received",
      "localization": {
        "ru": {
          "displayName": "Получена покупка"
        },
        "en": {
          "displayName": "Purchase received"
        }
      },
      "payloadSchema": {
        "type": "object",
        "properties": {
          "purchaseId": {
            "type": "string"
          },
          "recipient": {
            "type": "string"
          },
          "categoryId": {
            "type": "string"
          },
          "customFields": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": [
          "purchaseId",
          "recipient"
        ],
        "additionalProperties": false
      },
      "scopeSchema": {
        "type": "object",
        "properties": {
          "conversationId": {
            "type": "string"
          }
        },
        "required": [
          "conversationId"
        ],
        "additionalProperties": false
      },
      "selectors": [
        {
          "id": "category-id",
          "displayName": "Category",
          "source": "payload",
          "path": "categoryId",
          "operators": [
            "equals"
          ]
        },
        {
          "id": "recipient",
          "displayName": "Recipient",
          "source": "payload",
          "path": "recipient",
          "operators": [
            "exists",
            "equals",
            "contains"
          ],
          "localization": {
            "ru": {
              "displayName": "Получатель"
            },
            "en": {
              "displayName": "Recipient"
            }
          }
        }
      ],
      "bindingFields": [
        {
          "id": "recipient",
          "source": "payload",
          "path": "recipient",
          "valueSchema": {
            "type": "string"
          },
          "displayName": "Recipient",
          "localization": {
            "ru": {
              "displayName": "Получатель"
            },
            "en": {
              "displayName": "Recipient"
            }
          },
          "recommended": true,
          "availability": "always"
        },
        {
          "id": "custom-field",
          "source": "payload",
          "path": "customFields",
          "valueSchema": {
            "type": "string"
          },
          "displayName": "Custom field",
          "localization": {
            "ru": {
              "displayName": "Дополнительное поле"
            },
            "en": {
              "displayName": "Custom field"
            }
          },
          "availability": "when-present",
          "keyed": {
            "guardPath": "categoryId",
            "guardParameter": "categoryId"
          }
        }
      ],
      "bindingCatalogs": [
        {
          "id": "example.categories",
          "version": "1.0.0",
          "displayName": "Category fields",
          "scope": {
            "displayName": "Category",
            "selectorId": "category-id",
            "guardParameter": "categoryId"
          },
          "valueFieldId": "custom-field",
          "choiceFieldId": "custom-field"
        }
      ],
      "identityFields": [
        "purchaseId"
      ],
      "inputResolvers": [
        {
          "id": "commerce.recipient-profile",
          "version": "1.0.0",
          "displayName": "Recipient profile",
          "outputSchema": {
            "type": "object",
            "additionalProperties": true
          },
          "mode": "deferred",
          "localization": {
            "ru": {
              "displayName": "Профиль получателя"
            },
            "en": {
              "displayName": "Recipient profile"
            }
          },
          "requiredContext": [
            {
              "source": "scope",
              "path": "conversationId"
            }
          ],
          "timeoutMs": 30000,
          "retry": {
            "maxAttempts": 3,
            "initialBackoffMs": 1000
          },
          "ui": {
            "category": "Customer data",
            "order": 20
          }
        }
      ],
      "ui": {
        "category": "Sales",
        "icon": "cart"
      }
    }
  ],
  "abstractions": [
    {
      "abstractionId": "messaging.send-in-context",
      "abstractionVersion": "1.0.0",
      "nodeType": "example.delivery/send-message",
      "nodeVersion": "1.0.0"
    }
  ],
  "package": {
    "branding": {
      "icon": "assets/icon.png"
    },
    "artifact": {
      "path": "edge/driver.py",
      "filename": "driver.py"
    },
    "guides": {
      "installation": {
        "ru": "guides/install.ru.md",
        "en": "guides/install.en.md"
      },
      "readme": {
        "ru": "guides/README.ru.md",
        "en": "guides/README.en.md"
      },
      "changelog": {
        "ru": "guides/CHANGELOG.ru.md",
        "en": "guides/CHANGELOG.en.md"
      }
    },
    "compatibility": {
      "environments": [
        "Example Runtime 1.x"
      ]
    },
    "release": {
      "critical": false
    }
  }
}

Минимальная структура архива

Обычная структура: manifest.json, edge/driver.py и guides/install.ru.md. Дополнительно можно вложить guides/install.en.md и PNG/JPEG/WebP-иконку.

Buywell проверяет безопасные пути, размер, число файлов, UTF-8 Markdown, тип изображений и все ссылки на вложенные файлы. Digest рассчитывается по каноническому manifest и содержимому архива, поэтому порядок ZIP entries и timestamps не меняют идентичность пакета.

События и данные

Событие объявляет версию, payload/scope schemas и обязательные identity fields. Trigger selectors и binding fields намеренно разделены: первые разрешают фильтрацию запуска, вторые — выбор типизированного значения как входа сценария.

  • Не публикуйте произвольные JSON paths в UI.
  • Отмечайте чувствительные поля.
  • Deferred resolver объявляет только действительно необходимый event context.

Блоки и Edge

Действие принимает объявленные inputs/config и возвращает типизированные outputs. Условие дополнительно выбирает одну объявленную ветку. Edge-драйвер подключается исходящим соединением и подтверждает точные module ID, version и package digest.

Buywell сохраняет задания и может доставить незавершённое действие повторно. Драйвер обязан обрабатывать idempotency key и возвращать корреляцию исходного запроса.

  • Не храните credentials в пакете.
  • Не полагайтесь на соединение как на источник состояния выполнения.
  • Возвращайте только данные, соответствующие output schema.

Установка и обновления

1.0.0Текущие сценарии остаются закреплены
1.1.0Устанавливается рядом
Явный выборОбновить или откатить

UI, API и live registration используют один валидатор ZIP-пакета. Новая версия устанавливается рядом со старой и не мигрирует сценарии скрыто. Откат выбирает уже установленную точную версию.

Пакет, на который ссылается черновик или опубликованный сценарий, удалить нельзя. Инструкция установки всегда читается из закреплённого архива и не зависит от внешнего сайта.