@weavix/tracker-plugin-sdk 0.0.1

package/AGENTS.md

@@ -0,0 +1,27 @@
+# @weavix/tracker-plugin-sdk — agents
+
+**Пакет:** core SDK (Weavix / npm). API идентичен internal, без `yateamApi`.
+
+## Импорты
+
+```typescript
+import { hostApi, trackerApi, uiApi, PluginActionError } from '@weavix/tracker-plugin-sdk';
+```
+
+Peer: `@weavix/tracker-api-types`, `@weavix/tracker-core`.
+
+## Правила
+
+- **hostApi** — хост; **trackerApi.v3** — REST.
+- **uiApi** — navigate, toaster, confirm.
+
+## Документация
+
+| Файл | Назначение |
+|------|------------|
+| [../../AGENTS.md](../../AGENTS.md) | Общий вход (таблица internal vs external) |
+| [../../docs/agent/COOKBOOK.md](../../docs/agent/COOKBOOK.md) | Рецепты (блок External) |
+| [README.md](./README.md) | Быстрый старт |
+| [API_REFERENCE.md](./API_REFERENCE.md) | hostApi, uiApi, trackerApi.v3 |
+
+React: [@weavix/tracker-plugin-sdk-react](../tracker-react-external/AGENTS.md).

package/API_REFERENCE.md

@@ -0,0 +1,541 @@
+# API Reference - @weavix/tracker-plugin-sdk
+
+## Table of Contents
+
+- [hostApi (HostApi)](#hostapi-hostapi)
+  - [init()](#init)
+  - [getTheme()](#gettheme)
+  - [getLanguage()](#getlanguage)
+  - [getContext()](#getcontext)
+  - [updateContentSize()](#updatecontentsize)
+  - [notifyReady()](#notifyready)
+  - [getSlot()](#getslot)
+  - [getEntityId()](#getentityid)
+  - [getEntityMeta()](#getentitymeta)
+  - [getContextLevel()](#getcontextlevel)
+  - [disableAutoResize()](#disableautoresize)
+- [uiApi](#uiapi)
+  - [navigate()](#navigate)
+- [trackerApi (TrackerApi)](#trackerapi-trackerapi)
+  - [v3](#v3)
+- [Types](#types)
+  - [TrackerApiInitOptions](#trackerapiinitoptions)
+  - [TrackerApiCallOptions](#trackerapicalloptions)
+  - [TrackerApiV3](#trackerapiv3)
+  - [ApiCallResult](#apicallresult)
+  - [ApiCallPayload](#apicallpayload)
+  - [PluginActionError](#pluginactionerror)
+  - [Theme](#theme)
+  - [SlotContextMap](#slotcontextmap)
+  - [BasicContext](#basiccontext)
+  - [ContextLevel](#contextlevel)
+  - [ContentSizeUpdateRequest](#contentsizeupdaterequest)
+  - [HostInitOptions](#hostinitoptions)
+  - [NavigateRequest](#navigaterequest)
+- [Коды ошибок API](#коды-ошибок-api)
+- [Utils](#utils)
+  - [getLocalizedString()](#getlocalizedstring)
+  - [getField()](#getfield)
+- [Handlers](#handlers)
+
+---
+
+## hostApi (HostApi)
+
+API для взаимодействия с хостом (Tracker): инициализация плагина, тема, язык, контекст слота, размер окна, уведомление о готовности.
+
+Экспортируется singleton **`hostApi`**. Обычно используется внутри `TrackerPluginProvider` (пакет react); при необходимости можно вызывать напрямую.
+
+### init()
+
+Инициализирует плагин (чтение параметров из URL, инициализация моста, при необходимости — авто-ресайз). Вызывать один раз перед использованием остальных методов.
+
+**Parameters:** `options?: HostInitOptions` — опции (например `autoResize`, по умолчанию `true`).
+
+**Throws:** `Error` — если в URL нет обязательных параметров (slot, parentOrigin, id, elementId).
+
+```typescript
+import { hostApi } from '@weavix/tracker-plugin-sdk';
+
+hostApi.init({ autoResize: true });
+```
+
+---
+
+### getTheme()
+
+Возвращает текущую тему хоста.
+
+**Returns:** `Promise<Theme>`
+
+```typescript
+const theme = await hostApi.getTheme(); // 'light' | 'light-hc' | 'dark' | 'dark-hc' | 'system'
+```
+
+---
+
+### getLanguage()
+
+Возвращает текущий язык хоста.
+
+**Returns:** `Promise<string>` (например `'ru'`, `'en'`).
+
+```typescript
+const language = await hostApi.getLanguage();
+```
+
+---
+
+### getContext()
+
+Возвращает контекст слота, в котором запущен плагин. Тип зависит от слота (см. [SlotContextMap](#slotcontextmap)).
+
+**Returns:** `Promise<SlotContextMap[TSlot]>`
+
+```typescript
+const context = await hostApi.getContext();
+```
+
+---
+
+### updateContentSize()
+
+Отправляет хосту запрос на изменение высоты окна плагина.
+
+**Parameters:** `payload: ContentSizeUpdateRequest` (поле `height`).
+
+**Returns:** `Promise<…>`
+
+```typescript
+await hostApi.updateContentSize({ height: 500 });
+```
+
+---
+
+### notifyReady()
+
+Сообщает хосту, что плагин готов к работе.
+
+**Returns:** `Promise<…>`
+
+```typescript
+await hostApi.notifyReady();
+```
+
+---
+
+### getSlot()
+
+Возвращает текущий слот. Вызывать только после `init()`.
+
+**Returns:** `TSlot` (ключ из SlotContextMap).
+
+```typescript
+const slot = hostApi.getSlot(); // например 'issue.action'
+```
+
+---
+
+### getEntityId()
+
+Возвращает идентификатор сущности, переданный хостом в параметрах iframe. Доступен сразу после `init()` без postMessage-запроса.
+
+**Returns:** `string | null` — идентификатор сущности или `null`, если параметр не передан.
+
+```typescript
+const entityId = hostApi.getEntityId(); // например 'QUEUE-1' или null
+```
+
+---
+
+### getEntityMeta()
+
+Возвращает метаданные сущности, переданные хостом в параметрах iframe (JSON-объект). Доступны сразу после `init()` без postMessage-запроса.
+
+**Returns:** `Record<string, string> | undefined` — объект с метаданными или `undefined`, если метаданных нет.
+
+```typescript
+const entityMeta = hostApi.getEntityMeta(); // например { key: 'QUEUE-1' } или undefined
+```
+
+---
+
+### getContextLevel()
+
+Возвращает уровень контекста, объявленный в манифесте плагина (через параметр iframe `contextLevel`).
+
+- `'basic'` — плагин получает только `entityId` и `entityMeta` без postMessage-запроса к хосту.
+- `'full'` — плагин получает полный контекст слота через `context.get` (поведение по умолчанию).
+
+**Returns:** `ContextLevel` (`'basic' | 'full'`). По умолчанию `'full'`.
+
+```typescript
+const level = hostApi.getContextLevel(); // 'basic' | 'full'
+```
+
+---
+
+### disableAutoResize()
+
+Отключает автоматическое изменение размера контейнера по контенту.
+
+```typescript
+hostApi.disableAutoResize();
+```
+
+---
+
+## uiApi
+
+Singleton **`uiApi`** — UI-взаимодействия с хостом: навигация, тосты (`uiApi.toaster`), confirm (`uiApi.confirm`).
+
+### navigate()
+
+Выполнить навигацию в хост-приложении (путь Tracker, внешний URL и т.д.).
+
+**Parameters:** `NavigateRequest` (см. [тип](#navigaterequest))
+
+**Returns:** `Promise<void>`
+
+```typescript
+import { uiApi } from '@weavix/tracker-plugin-sdk';
+
+await uiApi.navigate({
+  path: '/issues/QUEUE-1',
+  params: { tab: 'comments' },
+  options: { newTab: false },
+});
+```
+
+---
+
+## trackerApi (TrackerApi)
+
+Класс для вызова Tracker Public API через хост (контракт `api.tracker.call`). Доступ к эндпоинтам — через типизированное API **v3**.
+
+Описание методов и форматов ответов: [Common format](https://docs.yandex-team.ru/tracker/common-format).
+
+Экспортируется singleton **`trackerApi`**.
+
+### v3
+
+Объект с методами по HTTP: `get`, `post`, `put`, `patch`, `delete`. Ключи — пути эндпоинтов из OpenAPI (`@weavix/tracker-api-types`); при обращении по пути IDE показывает подсказки и JSDoc.
+
+**Примеры:**
+
+```typescript
+import { trackerApi } from '@weavix/tracker-plugin-sdk';
+
+// GET — результат: { data, headers }
+const { data, headers } = await trackerApi.v3.get['/issues/{id}']({
+  pathParams: { id: 'QUEUE-123' },
+  queryParams: { expand: ['COMMENTS'] },
+});
+
+// POST
+await trackerApi.v3.post['/v2/issues']({
+  bodyParams: { queue: { key: 'TASK' }, summary: 'Новая задача' },
+});
+```
+
+- **v3.get[path](payload)** — GET; `payload`: `pathParams`, опционально `queryParams`.
+- **v3.post[path](payload)** / **put** / **patch** — в `payload` передаётся `bodyParams` (и при необходимости `pathParams`, `queryParams`).
+- **v3.delete[path](payload)** — DELETE; `payload`: `pathParams`, опционально `queryParams`.
+
+**Результат** — объект с полями **`data`** (тело ответа) и **`headers`** (полезные заголовки, `Record<string, string>`). По форме это совпадает с типом [`ApiCallResult`](#apicallresult) на стороне контракта с хостом; в **`trackerApi.v3`** TypeScript выводит для **`data`** конкретный тип ответа эндпоинта, а не `unknown`.
+
+Во все запросы через `trackerApi.v3` в контракт уходит **version: 'v3'**.
+
+```typescript
+const { data, headers } = await trackerApi.v3.get['/issues/{id}']({
+  pathParams: { id: 'QUEUE-123' },
+});
+// data — типизирован по OpenAPI; headers — Record<string, string>
+```
+
+---
+
+## Types
+
+### TrackerApiInitOptions
+
+Опции при создании экземпляра TrackerApi (если будет использоваться не singleton). Сейчас из core экспортируется только `trackerApi`, опции не передаются.
+
+```typescript
+interface TrackerApiInitOptions {
+  apiVersion?: string;
+}
+```
+
+---
+
+### TrackerApiCallOptions
+
+Параметры вызова эндпоинта в v3: `pathParams`, `queryParams`, `bodyParams`.
+
+```typescript
+interface TrackerApiCallOptions {
+  pathParams?: Record<string, string>;
+  queryParams?: Record<string, unknown>;
+  bodyParams?: Record<string, unknown>;
+}
+```
+
+---
+
+### TrackerApiV3
+
+Тип объекта `trackerApi.v3`: для каждого пути — вызов с тем же `payload`, что в типах API, а промис резолвится в **`{ data, headers }`**, где **`data`** имеет тип тела ответа этого эндпоинта.
+
+---
+
+### ApiCallResult
+
+Результат вызова Tracker API через хост (`api.tracker.call`). Экспортируется из пакета.
+
+```typescript
+type ApiCallResult = {
+  /** Тело ответа API */
+  data: unknown;
+  /** Полезные заголовки ответа (нормализованы в строки) */
+  headers: Record<string, string>;
+};
+```
+
+---
+
+### ApiCallPayload
+
+Полезная нагрузка, которую SDK отправляет хосту при вызове API. Обычно собирается внутри `trackerApi`; тип экспортируется для типизации на стороне хоста/обработчиков.
+
+```typescript
+type ApiCallPayload = {
+  version: string;
+  method: string;
+  url: string;
+  pathParams: Record<string, string>;
+  queryParams: Record<string, unknown>;
+  bodyParams: Record<string, unknown>;
+};
+```
+
+---
+
+### PluginActionError
+
+Ошибка действия плагина (в т.ч. при вызове Tracker API через мост). Экспортируется класс **`PluginActionError`**.
+
+- **`code`** — числовой код ошибки (см. [Коды ошибок API](#коды-ошибок-api)).
+- **`message`** — текст сообщения.
+- **`errorData`** (опционально) — объект/данные ошибки, которые вернул сервер (тело ответа или структурированная ошибка), если хост их передал.
+
+```typescript
+import { PluginActionError } from '@weavix/tracker-plugin-sdk';
+
+try {
+  await trackerApi.v3.get['/issues/{id}']({ pathParams: { id: 'BAD' } });
+} catch (e) {
+  if (e instanceof PluginActionError) {
+    console.log(e.code, e.message, e.errorData);
+  }
+}
+```
+
+---
+
+### Theme
+
+Тип темы оформления хоста.
+
+```typescript
+type Theme = 'light' | 'light-hc' | 'dark' | 'dark-hc' | 'system';
+```
+
+---
+
+### SlotContextMap
+
+Маппинг имён слотов на типы контекста. Например, слот `issue.action` даёт контекст типа `Issue`. Типы контекста и мапа (`SlotContextMap`, `Issue` в слоте и др.) задаются пакетом **`@weavix/tracker-core`** и реэкспортируются из core.
+
+```typescript
+// Пример: для слота 'issue.action' getContext() вернёт Issue
+const context = await hostApi.getContext();
+```
+
+---
+
+### BasicContext
+
+Базовый контекст плагина — доступен при `contextLevel = 'basic'` в манифесте. Содержит только данные из параметров iframe, без postMessage-запроса к хосту.
+
+```typescript
+type BasicContext = {
+  /** Идентификатор сущности (например, ключ задачи 'QUEUE-1') */
+  entityId: string;
+  /** Метаданные сущности, переданные хостом */
+  entityMeta?: Record<string, string>;
+};
+```
+
+Используется как тип `slotContext` при вызове `useTrackerPluginContext()` или `useTrackerPluginContext('basic')` в react-пакете.
+
+---
+
+### ContextLevel
+
+Уровень контекста, объявляемый в манифесте плагина в поле `contextLevel` слота.
+
+```typescript
+type ContextLevel = 'basic' | 'full';
+```
+
+- `'basic'` — плагин получает только `entityId` и `entityMeta` из параметров iframe. Вызов `context.get` не выполняется.
+- `'full'` — плагин получает полный контекст слота через postMessage (`context.get`). Поведение по умолчанию.
+
+**Пример в манифесте:**
+
+```json
+{
+  "slots": {
+    "tracker": {
+      "issue.action": [
+        {
+          "entrypoint": "index.html",
+          "contextLevel": "basic"
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### ContentSizeUpdateRequest
+
+Запрос на изменение размера контента плагина.
+
+```typescript
+type ContentSizeUpdateRequest = { height?: number };
+```
+
+---
+
+### HostInitOptions
+
+Опции инициализации хоста (передаются в `hostApi.init()`).
+
+```typescript
+interface HostInitOptions {
+  /** Авто-ресайз по контенту, по умолчанию true */
+  autoResize?: boolean;
+}
+```
+
+---
+
+### NavigateRequest
+
+Запрос на навигацию в хосте (`uiApi.navigate`).
+
+```typescript
+type NavigateRequest = {
+  path: string;
+  params?: Record<string, string | number | boolean | null | undefined | (string | number | boolean | null | undefined)[]>;
+  options?: {
+    newTab?: boolean;
+  };
+};
+```
+
+---
+
+## Коды ошибок API
+
+При вызовах методов хост может вернуть ошибку с кодом. Константы экспортируются из пакета:
+
+```typescript
+import {
+  METHOD_NOT_SUPPORTED,
+  MISSING_REQUIRED_SCOPE,
+  PLUGIN_ID_IS_NOT_CORRECT,
+  PLUGIN_ID_OR_SLOT_NOT_PROVIDED,
+  UNKNOWN_ERROR,
+  VALIDATION_ERROR,
+} from '@weavix/tracker-plugin-sdk';
+```
+
+| Константа | Код | Описание |
+|-----------|-----|----------|
+| `PLUGIN_ID_OR_SLOT_NOT_PROVIDED` | 1000 | Не переданы обязательные параметры инициализации плагина. |
+| `PLUGIN_ID_IS_NOT_CORRECT` | 1001 | Неверный или несовпадающий pluginId. |
+| `VALIDATION_ERROR` | 1002 | Ошибка валидации запроса. |
+| `METHOD_NOT_SUPPORTED` | 1003 | Метод не поддерживается. |
+| `MISSING_REQUIRED_SCOPE` | 1004 | Недостаточно прав (scope). |
+| `UNKNOWN_ERROR` | 6666 | Неизвестная ошибка. |
+
+---
+
+## Utils
+
+### getLocalizedString()
+
+Возвращает локализованную строку по коду языка. Тип `LocalizedString` приходит из **`@weavix/tracker-core`** (реэкспорт из core).
+
+```typescript
+function getLocalizedString(
+  value: LocalizedString,
+  language: string,
+  fallbackLanguage?: string,
+): string;
+```
+
+### getField()
+
+Извлекает значение из объекта по точечному пути (dot notation).
+
+```typescript
+function getField<T = unknown>(
+  obj: Record<string, unknown>,
+  path: string,
+  defaultValue?: T,
+): T | undefined;
+```
+
+---
+
+## Handlers
+
+Экспортируются **getHandler**, **setHandler**, типы **HandlerFunction**, **Handlers**, **HttpMethod** — для регистрации обработчиков запросов со стороны хоста (см. контракт и слоты).
+
+---
+
+## Complete Example
+
+```typescript
+import {
+  hostApi,
+  trackerApi,
+  getField,
+  type Theme,
+} from '@weavix/tracker-plugin-sdk';
+
+// Инициализация обычно выполняется в TrackerPluginProvider (react)
+hostApi.init({ autoResize: true });
+
+const theme: Theme = await hostApi.getTheme();
+const language = await hostApi.getLanguage();
+const context = await hostApi.getContext();
+
+// Вызов Tracker API v3 (в payload уходит version: 'v3')
+const { data: issue } = await trackerApi.v3.get['/issues/{id}']({
+  pathParams: { id: 'KEY-1' },
+  queryParams: { expand: ['COMMENTS'] },
+});
+
+const summary = getField<string>(issue as Record<string, unknown>, 'summary', 'Без названия');
+
+await hostApi.notifyReady();
+```
+
+Типы **HTTP** запросов/ответов эндпоинтов (в т.ч. `Issue` в ответе REST) задаются пакетом **@weavix/tracker-api-types**. Типы **контекста слота** и `SlotContextMap` — из **@weavix/tracker-core** (см. выше).

package/README.md

@@ -0,0 +1,363 @@
+# @weavix/tracker-plugin-sdk
+
+Core package for Tracker plugins (Weavix / npm). API surface matches `@yandex-data-ui/tracker-plugin-sdk-core` without `yateamApi`.
+
+> External flavor. Internal (Yandex): `@yandex-data-ui/tracker-plugin-sdk-core`.
+
+Низкоуровневое API для взаимодействия с хостом и вызова Tracker Public API.
+
+> **Для агентов и AI:** начните с [AGENTS.md](./AGENTS.md) и [COOKBOOK](../../docs/agent/COOKBOOK.md).
+
+## Установка
+
+```bash
+npm install @weavix/tracker-plugin-sdk
+```
+
+## Использование
+
+```typescript
+import { hostApi, trackerApi } from '@weavix/tracker-plugin-sdk';
+
+// Инициализация плагина (чтение параметров из URL, настройка моста)
+hostApi.init({ autoResize: true });
+
+// Получение текущей темы
+const theme = await hostApi.getTheme(); // 'light' | 'light-hc' | 'dark' | 'dark-hc' | 'system' | undefined
+
+// Получение текущего языка
+const language = await hostApi.getLanguage(); // 'ru' | 'en' | undefined 
+
+// Получение контекста слота (например, текущей задачи для слота 'issue.action')
+const context = await hostApi.getContext();
+
+// Уведомление хоста о готовности плагина
+await hostApi.notifyReady();
+
+// Обновление высоты контейнера плагина
+await hostApi.updateContentSize({ height: 500 });
+```
+
+## Tracker API
+
+Все вызовы Tracker Public API выполняются через `trackerApi.v3` — типизированный прокси над HTTP-методами. Ключи — пути эндпоинтов из OpenAPI (`@weavix/tracker-api-types`); IDE предоставляет автодополнение и JSDoc.
+
+Подробное описание методов и форматов ответов: [Tracker API Reference](https://docs.yandex-team.ru/tracker/api-ref/about-api).
+
+```typescript
+import { trackerApi } from '@weavix/tracker-plugin-sdk';
+
+// GET — возвращает { data, headers }
+const { data: issue } = await trackerApi.v3.get['/issues/{id}']({
+  pathParams: { id: 'QUEUE-123' },
+  queryParams: { expand: ['COMMENTS'] },
+});
+
+// POST
+await trackerApi.v3.post['/v2/issues']({
+  bodyParams: { queue: { key: 'TASK' }, summary: 'Новая задача' },
+});
+
+// PATCH
+await trackerApi.v3.patch['/v2/issues/{id}']({
+  pathParams: { id: 'QUEUE-123' },
+  bodyParams: { summary: 'Обновлённое название' },
+});
+
+// DELETE
+await trackerApi.v3.delete['/v2/issues/{id}']({
+  pathParams: { id: 'QUEUE-123' },
+});
+```
+
+### Очереди
+
+```typescript
+// Получение списка очередей
+const { data: queues } = await trackerApi.v3.get['/v2/queues']({
+  queryParams: { page: 1, perPage: 100 },
+});
+
+// Получение конкретной очереди
+const { data: queue } = await trackerApi.v3.get['/v2/queues/{id}']({
+  pathParams: { id: 'MYQUEUE' },
+});
+```
+
+### Задачи
+
+```typescript
+// Получение задачи по ключу
+const { data: issue } = await trackerApi.v3.get['/issues/{id}']({
+  pathParams: { id: 'QUEUE-123' },
+});
+
+// Создание задачи
+const { data: newIssue } = await trackerApi.v3.post['/v2/issues']({
+  bodyParams: {
+    queue: { key: 'QUEUE' },
+    summary: 'Название задачи',
+  },
+});
+
+// Поиск задач
+const { data: issues } = await trackerApi.v3.post['/v2/issues/_search']({
+  bodyParams: { filter: { queue: 'QUEUE' } },
+});
+```
+
+## Тосты (Toast notifications)
+
+Плагины могут показывать toast-уведомления в хост-приложении через `uiApi.toaster`. API максимально приближен к gravity-ui `useToaster`.
+
+> **Permission:** Требуется `"toaster"` в `permissions.ui` манифеста плагина (хост преобразует в scope `tracker:ui:toaster`).
+
+```typescript
+import { uiApi } from '@weavix/tracker-plugin-sdk';
+
+// Простой тост
+uiApi.toaster.add({
+  title: 'Сохранено',
+  theme: 'success',
+});
+
+// Тост с текстовым содержимым и кастомным временем показа
+uiApi.toaster.add({
+  title: 'Ошибка',
+  theme: 'danger',
+  content: 'Не удалось загрузить данные',
+  autoHiding: 10000,
+});
+
+// Тост с кнопкой действия
+uiApi.toaster.add({
+  title: 'Элемент удалён',
+  theme: 'info',
+  content: 'QUEUE-123',
+  actions: [
+    {
+      label: 'Отменить',
+      onClick: () => {
+        // обработка нажатия
+      },
+    },
+  ],
+});
+```
+
+### `uiApi.toaster.add(options)`
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| `title` | `string` | — | Заголовок тоста (обязательный) |
+| `name` | `string` | auto | Уникальный ключ для дедупликации. Генерируется автоматически, если не передан |
+| `theme` | `'success' \| 'danger' \| 'warning' \| 'info'` | `'info'` | Тема (цвет и иконка) |
+| `content` | `string` | — | Текстовое содержимое под заголовком |
+| `autoHiding` | `number` | `5000` | Время показа в мс (от 1000 до 30000) |
+| `isClosable` | `boolean` | `true` | Показывать кнопку закрытия |
+| `actions` | `ToastAction[]` | — | Кнопки действий (макс. 2) |
+
+**`ToastAction`:**
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `label` | `string` | Текст кнопки (макс. 50 символов) |
+| `onClick` | `() => void` | Callback при нажатии |
+
+**Возвращает:** `Promise<{ name: string }>` — имя тоста (для идентификации).
+
+**Ограничения:**
+- `title` — макс. 200 символов
+- `content` — макс. 500 символов
+- `actions` — макс. 2 кнопки
+- Rate limit — 5 тостов за 10 секунд на плагин
+
+## Навигация в хосте
+
+Плагин может открыть путь в хост-приложении или внешний URL через `uiApi.navigate`:
+
+```typescript
+import { uiApi } from '@weavix/tracker-plugin-sdk';
+
+await uiApi.navigate({
+  path: '/queues/MYQUEUE',
+  params: { tab: 'settings' },
+  options: { newTab: true },
+});
+```
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `path` | `string` | Путь или URL (обязательный) |
+| `params` | `Record<string, string \| number \| boolean \| null \| undefined \| (string \| number \| boolean \| null \| undefined)[]>` | Query-параметры |
+| `options.newTab` | `boolean` | Открыть в новой вкладке |
+
+`TrackerPluginProvider` (react) перехватывает клики по внешним ссылкам в iframe и вызывает `uiApi.navigate`.
+
+## Storage API
+
+`storageApi` — JSON-хранилище уровня организации, опосредованное хостом. Запись общая на всю организацию: её видят все пользователи плагина, право на запись определяет хост (отдаёт его в поле `canWrite` каждой прочитанной записи).
+
+На сегодня доступен единственный контекст — `storageApi.orgShared`.
+
+```typescript
+import { storageApi } from '@weavix/tracker-plugin-sdk';
+
+// Чтение
+const record = await storageApi.orgShared.get('settings');
+// record: { data: { theme: 'dark' }, version: 5, canWrite: true, ... } | null
+
+// Создание новой записи (на пустом бакете)
+await storageApi.orgShared.patch({
+    bucket: 'settings',
+    data: { theme: 'dark', notifications: true },
+    version: 0,
+});
+
+// Обновление без знания текущей версии — SDK сам вычитает её и поретраит конфликты
+await storageApi.orgShared.patch({
+    bucket: 'settings',
+    data: { count: 42 },
+});
+
+// Удаление отдельного поля — передайте `null`
+await storageApi.orgShared.patch({
+    bucket: 'settings',
+    data: { theme: null },
+});
+```
+
+### `storageApi.orgShared.get(bucket?)`
+
+Возвращает `Promise<StorageRecord | null>` — текущую запись или `null`, если её ещё нет.
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| `bucket` | `string \| undefined` | хост подставляет `'default'` | Ключ записи внутри контекста |
+
+### `storageApi.orgShared.patch(options)`
+
+Merge-patch: поля из `data` накладываются на текущую запись поверх, значение `null` удаляет ключ. Возвращает полный смерженный `StorageRecord` с новой версией (включая поля, дописанные параллельными писателями).
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|--------------|----------|
+| `bucket` | `string` | хост подставляет `'default'` | Ключ записи |
+| `data` | `Record<string, unknown>` | — | Merge-doc; `null` удаляет поле |
+| `version` | `number \| undefined` | auto-resolve | Ожидаемая текущая версия |
+
+**Версионирование.**
+
+- **С явным `version`** — отправляется один запрос. Любая ошибка, включая `VERSION_CONFLICT`, пробрасывается вызывающему. Используйте, если приложение само держит актуальную версию и должно реагировать на конфликт (например, показать пользователю «данные изменились, перечитайте»). Для создания записи на пустом бакете передавайте `version: 0`.
+- **Без `version`** — SDK сначала читает текущую версию через `get` (для пустого бакета берётся `0`), затем выполняет `patch`. На `VERSION_CONFLICT` цикл повторяется до двух раз, каждый ретрай заново читает версию. Любая другая ошибка пробрасывается мгновенно. В худшем случае — 6 round-trip-ов (3 пары GET + PATCH); на каждом ретрае в консоль пишется `console.warn`.
+
+### Ошибки
+
+Все ошибки storage-методов — экземпляры `PluginActionError` с числовыми кодами:
+
+| Код | Константа | Когда |
+|-----|-----------|-------|
+| `1010` | `VERSION_CONFLICT` | Переданный `version` не совпал с текущим |
+| `1011` | `DATA_TOO_LARGE` | Размер записи после операции превысил 256 KiB |
+| `1012` | `BAD_KEY` | `bucket` не прошёл валидацию формата или длины |
+
+```typescript
+import { PluginActionError, VERSION_CONFLICT, storageApi } from '@weavix/tracker-plugin-sdk';
+
+try {
+    await storageApi.orgShared.patch({ bucket: 'settings', data: { x: 1 }, version: 0 });
+} catch (e) {
+    if (e instanceof PluginActionError && e.code === VERSION_CONFLICT) {
+        // показать пользователю, что версия устарела
+    }
+}
+```
+
+### Типы
+
+```typescript
+import type {
+    StorageContextType,  // 'orgShared' (расширяемое в будущем)
+    StorageRecord,       // { key, version, data, canWrite, createdAt, updatedAt }
+    StorageGetPayload,   // wire-payload для storage.get
+    StoragePatchPayload, // wire-payload для storage.patch
+} from '@weavix/tracker-plugin-sdk';
+```
+
+## Обработка ошибок
+
+```typescript
+import { trackerApi, PluginActionError } from '@weavix/tracker-plugin-sdk';
+
+try {
+  await trackerApi.v3.get['/issues/{id}']({ pathParams: { id: 'BAD' } });
+} catch (e) {
+  if (e instanceof PluginActionError) {
+    console.log(e.code, e.message, e.errorData);
+  }
+}
+```
+
+## API
+
+### `hostApi`
+
+- `init(options?)` — инициализация плагина (чтение параметров из URL, настройка моста). Вызывать один раз перед использованием остальных методов.
+- `getTheme()` — текущая тема (`'light' | 'light-hc' | 'dark' | 'dark-hc' | 'system'`)
+- `getLanguage()` — текущий код языка (`'ru'`, `'en'` и др.)
+- `getContext()` — контекст слота (тип зависит от слота, см. `SlotContextMap`)
+- `getSlot()` — имя текущего слота (вызывать после `init()`)
+- `updateContentSize(request)` — обновление высоты контейнера плагина
+- `notifyReady()` — уведомление хоста о готовности плагина
+- `disableAutoResize()` — отключение автоматического изменения размера
+
+### `uiApi`
+
+UI-методы хоста (навигация, тосты, confirm и др.).
+
+- `uiApi.navigate(request)` — навигация в хост-приложении. Подробности — [выше](#навигация-в-хосте).
+- `uiApi.toaster.add(options)` — показать toast-уведомление в хост-приложении. Подробности — [выше](#тосты-toast-notifications).
+- `uiApi.confirm.show(options)` — диалог подтверждения (permission `confirm` в манифесте).
+
+### `trackerApi.v3`
+
+Типизированный прокси над эндпоинтами Tracker Public API v3:
+
+- `trackerApi.v3.get[path](payload)` — GET-запрос; `payload`: `pathParams`, опционально `queryParams`
+- `trackerApi.v3.post[path](payload)` — POST-запрос; `payload`: `bodyParams`, опционально `pathParams`, `queryParams`
+- `trackerApi.v3.put[path](payload)` — PUT-запрос
+- `trackerApi.v3.patch[path](payload)` — PATCH-запрос
+- `trackerApi.v3.delete[path](payload)` — DELETE-запрос; `payload`: `pathParams`, опционально `queryParams`
+
+Все методы возвращают `Promise<{ data, headers }>`, где `data` типизирован согласно ответу эндпоинта.
+
+## Типы
+
+- **`SlotContextMap`**, контексты слотов, `LocalizedString` и связанные типы (`Issue` в контексте слота, `Attachment` и т.д.) — из **`@weavix/tracker-core`**, реэкспортируются из этого пакета.
+- Типы **запросов и ответов HTTP** эндпоинтов Tracker Public API (`trackerApi.v3`) — из **`@weavix/tracker-api-types`**.
+
+```typescript
+import type {
+  Theme,
+  ApiCallResult,
+  ApiCallPayload,
+  TrackerApiCallOptions,
+  ContentSizeUpdateRequest,
+  SlotContextMap,
+} from '@weavix/tracker-plugin-sdk';
+```
+
+## React-интеграция
+
+Для React-приложений используйте [@weavix/tracker-plugin-sdk-react](../tracker-react-external/README.md) — `TrackerPluginProvider`, `useTrackerPluginContext`, `useLocalizedString`.
+
+## Полная документация
+
+📖 [AGENTS.md](./AGENTS.md) — краткий вход для агентов.
+
+📖 [COOKBOOK](../../docs/agent/COOKBOOK.md) — типовые сценарии.
+
+📖 [API Reference](./API_REFERENCE.md) — hostApi, trackerApi.v3, типы, ошибки.
+
+## Лицензия
+
+UNLICENSED

package/dist/index.mjs

@@ -0,0 +1,28 @@
+import { trackerApi as r } from "@weavix/tracker-core";
+import { getHandler as o, getLocalizedString as E, hostApi as R, setHandler as i, storageApi as A } from "@weavix/tracker-core";
+import { BAD_KEY as N, DATA_TOO_LARGE as p, METHOD_NOT_SUPPORTED as T, MISSING_REQUIRED_SCOPE as D, PLUGIN_ID_IS_NOT_CORRECT as a, PLUGIN_ID_OR_SLOT_NOT_PROVIDED as n, PluginActionError as s, UNKNOWN_ERROR as S, VALIDATION_ERROR as c, VERSION_CONFLICT as L, dispatchHostEvent as P, getField as g, on as d, resetEventBus as l, uiApi as C } from "@weavix/sdk-core";
+const e = r;
+export {
+  N as BAD_KEY,
+  p as DATA_TOO_LARGE,
+  T as METHOD_NOT_SUPPORTED,
+  D as MISSING_REQUIRED_SCOPE,
+  a as PLUGIN_ID_IS_NOT_CORRECT,
+  n as PLUGIN_ID_OR_SLOT_NOT_PROVIDED,
+  s as PluginActionError,
+  S as UNKNOWN_ERROR,
+  c as VALIDATION_ERROR,
+  L as VERSION_CONFLICT,
+  P as dispatchHostEvent,
+  g as getField,
+  o as getHandler,
+  E as getLocalizedString,
+  R as hostApi,
+  d as on,
+  l as resetEventBus,
+  i as setHandler,
+  A as storageApi,
+  e as trackerApi,
+  C as uiApi
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../src/api/trackerApi.ts"],"sourcesContent":["import type {\n    ApiV3DeleteMethods,\n    ApiV3GetMethods,\n    ApiV3PatchMethods,\n    ApiV3PostMethods,\n    ApiV3PutMethods,\n} from '@weavix/tracker-api-types';\nimport {\n    type TrackerApiCallOptions as BaseCallOptions,\n    type TrackerApiInitOptions as BaseInitOptions,\n    trackerApi as trackerApiBase,\n} from '@weavix/tracker-core';\n\nexport type TrackerApiCallOptions = BaseCallOptions;\nexport type TrackerApiInitOptions = BaseInitOptions;\n\ntype ApiResult<M> = {\n    [K in keyof M]: M[K] extends (...args: infer A) => Promise<infer R>\n        ? (...args: A) => Promise<{ data: R; headers: Record<string, string> }>\n        : never;\n};\n\nexport interface TrackerApiV3 {\n    get: ApiResult<ApiV3GetMethods>;\n    post: ApiResult<ApiV3PostMethods>;\n    put: ApiResult<ApiV3PutMethods>;\n    patch: ApiResult<ApiV3PatchMethods>;\n    delete: ApiResult<ApiV3DeleteMethods>;\n}\n\nexport interface TrackerApi {\n    v3: TrackerApiV3;\n}\n\nexport const trackerApi = trackerApiBase as unknown as TrackerApi;\n"],"names":["trackerApi","trackerApiBase"],"mappings":";;;AAkCO,MAAMA,IAAaC;"}

package/dist/tracker-plugin-external/src/api/trackerApi.d.ts

@@ -0,0 +1,23 @@
+import { ApiV3DeleteMethods, ApiV3GetMethods, ApiV3PatchMethods, ApiV3PostMethods, ApiV3PutMethods } from '@weavix/tracker-api-types';
+import { TrackerApiCallOptions as BaseCallOptions, TrackerApiInitOptions as BaseInitOptions } from '@weavix/tracker-core';
+export type TrackerApiCallOptions = BaseCallOptions;
+export type TrackerApiInitOptions = BaseInitOptions;
+type ApiResult<M> = {
+    [K in keyof M]: M[K] extends (...args: infer A) => Promise<infer R> ? (...args: A) => Promise<{
+        data: R;
+        headers: Record<string, string>;
+    }> : never;
+};
+export interface TrackerApiV3 {
+    get: ApiResult<ApiV3GetMethods>;
+    post: ApiResult<ApiV3PostMethods>;
+    put: ApiResult<ApiV3PutMethods>;
+    patch: ApiResult<ApiV3PatchMethods>;
+    delete: ApiResult<ApiV3DeleteMethods>;
+}
+export interface TrackerApi {
+    v3: TrackerApiV3;
+}
+export declare const trackerApi: TrackerApi;
+export {};
+//# sourceMappingURL=trackerApi.d.ts.map

package/dist/tracker-plugin-external/src/api/trackerApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackerApi.d.ts","sourceRoot":"","sources":["../../../../src/api/trackerApi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACH,KAAK,qBAAqB,IAAI,eAAe,EAC7C,KAAK,qBAAqB,IAAI,eAAe,EAEhD,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC;AACpD,MAAM,MAAM,qBAAqB,GAAG,eAAe,CAAC;AAEpD,KAAK,SAAS,CAAC,CAAC,IAAI;KACf,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAC7D,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,GACrE,KAAK;CACd,CAAC;AAEF,MAAM,WAAW,YAAY;IACzB,GAAG,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAClC,GAAG,EAAE,SAAS,CAAC,eAAe,CAAC,CAAC;IAChC,KAAK,EAAE,SAAS,CAAC,iBAAiB,CAAC,CAAC;IACpC,MAAM,EAAE,SAAS,CAAC,kBAAkB,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,UAAU;IACvB,EAAE,EAAE,YAAY,CAAC;CACpB;AAED,eAAO,MAAM,UAAU,EAAgC,UAAU,CAAC"}

package/dist/tracker-plugin-external/src/index.d.ts

@@ -0,0 +1,19 @@
+export { hostApi } from '@weavix/tracker-core';
+export type { ApiCallPayload, ApiCallResult, HostApi } from '@weavix/tracker-core';
+export { trackerApi } from './api/trackerApi';
+export type { TrackerApi, TrackerApiCallOptions, TrackerApiInitOptions, TrackerApiV3, } from './api/trackerApi';
+export type { ContentSizeUpdateRequest } from '../../plugin-sdk-core/src/index.ts';
+export { getHandler, setHandler } from '@weavix/tracker-core';
+export type { GetDataResultMap, HandlerFunction, Handlers, HttpMethod } from '@weavix/tracker-core';
+export { dispatchHostEvent, on, resetEventBus } from '../../plugin-sdk-core/src/index.ts';
+export type { EventMessage, HostEventCallback, HostEventContract, HostEventMethod, Unsubscribe, } from '../../plugin-sdk-core/src/index.ts';
+export { BAD_KEY, DATA_TOO_LARGE, METHOD_NOT_SUPPORTED, MISSING_REQUIRED_SCOPE, PLUGIN_ID_IS_NOT_CORRECT, PLUGIN_ID_OR_SLOT_NOT_PROVIDED, PluginActionError, UNKNOWN_ERROR, VALIDATION_ERROR, VERSION_CONFLICT, } from '../../plugin-sdk-core/src/index.ts';
+export type { BasicContext, ContextLevel, Theme } from '../../plugin-sdk-core/src/index.ts';
+export type { Attachment, AttachmentViewerActionSlotContext, BoardTabSlotContext, GoalSlotContext, Issue, IssueCommentActionSlotContext, LocalizedString, MetaEntityV2, PortfolioSlotContext, ProjectSlotContext, SlotContextMap, TriggerActionData, TriggerCreateActionsSlotContext, TriggerEditActionsSlotContext, } from '@weavix/tracker-core';
+export { uiApi } from '../../plugin-sdk-core/src/index.ts';
+export type { ConfirmOptions, ConfirmResult, ToastAction, ToastOptions } from '../../plugin-sdk-core/src/index.ts';
+export { getField } from '../../plugin-sdk-core/src/index.ts';
+export { getLocalizedString } from '@weavix/tracker-core';
+export { storageApi } from '@weavix/tracker-core';
+export type { StorageContextType, StorageGetPayload, StoragePatchPayload, StorageRecord, } from '@weavix/tracker-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/tracker-plugin-external/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EACR,UAAU,EACV,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,GACf,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAGjE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGpG,OAAO,EAAE,iBAAiB,EAAE,EAAE,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACxE,YAAY,EACR,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,WAAW,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACH,OAAO,EACP,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,8BAA8B,EAC9B,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC1E,YAAY,EACR,UAAU,EACV,iCAAiC,EACjC,mBAAmB,EACnB,eAAe,EACf,KAAK,EACL,6BAA6B,EAC7B,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,+BAA+B,EAC/B,6BAA6B,GAChC,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGjG,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,YAAY,EACR,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GAChB,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@weavix/tracker-plugin-sdk",
+  "version": "0.0.1",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md",
+    "API_REFERENCE.md"
+  ],
+  "keywords": [],
+  "author": "Tracker Team",
+  "license": "UNLICENSED",
+  "description": "Core package for Tracker plugin SDK (Weavix flavor)",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@weavix/sdk-core": "^0.0.3",
+    "@weavix/tracker-api-types": ">=0.0.0",
+    "@weavix/tracker-core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/jest": "*",
+    "@weavix/tracker-api-types": "*",
+    "@weavix/sdk-core": "0.0.0",
+    "@weavix/tracker-core": "0.0.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  }
+}