@axon-assistant/plugin-sdk 2026.8.23

package/README.md

@@ -0,0 +1,287 @@
+# @axon-assistant/plugin-sdk
+
+Типы для написания плагинов [Axon](https://github.com/bigtaed/axon).
+
+Пакет нужен только редактору. В рантайме плагину импортировать из него нечего:
+`api` приезжает аргументом в `activate`. Плагин без единой зависимости — папка,
+которую можно склонировать и запустить, а не проект, который надо сначала собрать.
+
+```bash
+npm i -D @axon-assistant/plugin-sdk
+```
+
+## Из чего состоит плагин
+
+```
+my-plugin/
+  axon.plugin.json   манифест — единственный обязательный файл
+  index.js           точка входа, если у плагина есть код
+  skills/*.md        инструкции текстом, если они есть
+```
+
+Плагин **без кода** — законная и частая вещь: манифест из десяти строк,
+поднимающий чужой MCP-сервер.
+
+## Манифест
+
+```json
+{
+  "id": "weather",
+  "name": "Погода",
+  "description": "Прогноз для города пользователя",
+  "version": "1.0.0",
+  "api": 1,
+  "main": "./index.js",
+  "permissions": ["net"],
+  "settings": [
+    { "key": "apiKey", "label": "Ключ OpenWeather", "type": "secret", "required": true },
+    { "key": "city", "label": "Город", "type": "text", "default": "Варшава" }
+  ],
+  "skills": "./skills",
+  "mcpServers": {},
+  "jobs": [{ "name": "утренняя-сводка", "everySeconds": 3600 }]
+}
+```
+
+| Поле | Смысл |
+| --- | --- |
+| `id` | Слаг. Им префиксуются инструменты: `search` → `weather_search` |
+| `api` | Версия API плагинов. Сейчас `1` |
+| `main` | Точка входа. Нет — плагин без кода |
+| `permissions` | `fs`, `net`, `shell`, `secrets`, `journal`. Показываются пользователю до установки |
+| `settings` | Форма, которую нарисует интерфейс. `secret` хранится шифрованным |
+| `skills` | Папка с `*.md` |
+| `mcpServers` | Имя → транспорт. `${ключ}` подставляется из настроек при запуске |
+| `jobs` | Задачи по расписанию. Обработчик вешается через `api.jobs.on` |
+
+## Код
+
+```js
+export async function activate(api) {
+  await api.tools.register({
+    name: 'forecast',
+    title: 'Прогноз погоды',
+    description:
+      'Узнать погоду в городе. Вызывай, когда спрашивают про погоду, ' +
+      'дождь, температуру или что надеть.',
+    tier: 'sensitive',
+    parameters: {
+      type: 'object',
+      properties: { city: { type: 'string', description: 'Город' } },
+      required: ['city'],
+    },
+    async execute({ city }) {
+      const key = api.settings.get('apiKey');
+      const res = await fetch(`https://api.openweathermap.org/…&q=${city}&appid=${key}`);
+      return JSON.stringify(await res.json());
+    },
+  });
+}
+
+export function deactivate() {}
+```
+
+`execute` возвращает строку или `{ text, mime }`.
+
+## Что даёт `api`
+
+| | |
+| --- | --- |
+| `api.tools.register/unregister` | свои инструменты |
+| `api.context.contribute(name, stability, fn)` | абзац в промпт |
+| `api.skills.add` | скилл на лету (обычно они просто файлы в `skills/`) |
+| `api.providers.register` | свой провайдер модели |
+| `api.jobs.on(name, fn)` | обработчик задачи из манифеста |
+| `api.journal.on(fn)` | события ядра (нужно право `journal`) |
+| `api.settings.get/set/onChange` | настройки плагина |
+| `api.memory.facts/remember` | долговременная память пользователя |
+| `api.blobs.write` | большой вывод мимо контекста модели |
+| `api.log.*` | в логи плагина, видные в интерфейсе |
+| `api.dir` / `api.dataDir` | своя папка и папка для своих данных |
+
+## Что плагин может попросить у ядра
+
+До сих пор SDK был про то, как плагин **отдаёт** возможности. Обратная сторона —
+четыре вещи, без которых серьёзный плагин не пишется.
+
+**Спросить модель.** Ту, которую человек уже настроил:
+
+```js
+const кратко = await api.model.ask({
+  system: 'Отвечай одним предложением.',
+  prompt: 'О чём этот текст?
+
+' + текст,
+  maxTokens: 300,
+});
+```
+
+Свой ключ заводить не нужно, и расход попадает в общий счётчик. Плагин с
+собственным ключом означал бы, что человек платит дважды и второй раз не видит
+за что.
+
+Это один вопрос без истории и без инструментов. Нужен агент — им уже является
+Axon; плагину незачем становиться вторым.
+
+**Сказать человеку.**
+
+```js
+await api.notify('Сервер упал', 'не отвечает третью минуту');
+```
+
+Показывает тот клиент, который сейчас на связи, — у ядра экрана нет. Мера, а не
+право: плагин, который звенит каждый час просто потому, что проснулся,
+выключают в тот же день вместе со всей пользой.
+
+**Сказать о себе.**
+
+```js
+await api.status.set('токен протух', true);   // покажется как «не работает»
+await api.status.clear();                      // всё наладилось
+```
+
+Состояние плагина ядро выводит из состояния процесса: жив — значит работает.
+Плагин, у которого отвалился внешний сервер, при этом живее всех живых и
+молчит, а человек гадает, почему инструмент не отвечает.
+
+**Поискать в переписке.**
+
+```js
+const найдено = await api.history.search('докер', 5);
+```
+
+Тот же поиск, что у агента. Плагин видел факты, но не разговоры — опереться на
+контекст было неоткуда.
+
+## Своя страница настроек
+
+Рядом с плагином в списке есть шестерёнка — за ней страница, которую описывает
+сам плагин. Описывает, а не рисует: ни разметки, ни кода для окна плагин не
+присылает. Пусти его рисовать самому — и код плагина окажется в окне с полным
+доступом к ядру, ровно там, откуда его убрали отдельным процессом.
+
+**Разделы** группируют поля. Плоский список годится, пока полей пять; дальше
+человек смотрит на два десятка подписей и не понимает, что с чем связано.
+
+```json
+"sections": [
+  {
+    "title": "Подключение",
+    "description": "Токен берётся в настройках вашего аккаунта.",
+    "fields": ["host", "token"]
+  }
+]
+```
+
+**Условные поля** появляются, только когда нужны:
+
+```json
+{ "key": "port", "label": "Порт", "type": "number",
+  "visibleWhen": { "key": "mode", "equals": "self-hosted" } }
+```
+
+Без этого плагин с двумя способами подключения вываливает поля обоих сразу, и
+человек заполняет половину впустую.
+
+**Кнопки** — то, ради чего страница вообще нужна: настройки без способа
+проверить, что они верные, это анкета, а не настройка.
+
+```json
+"actions": [
+  { "name": "check", "label": "Проверить подключение", "section": "Подключение" },
+  { "name": "reset", "label": "Сбросить кэш", "confirm": "Точно очистить?" }
+]
+```
+
+```js
+api.actions.on('check', async () => {
+  const response = await fetch(`${api.settings.get('host')}/ping`);
+  if (!response.ok) throw new Error(`Сервер ответил ${response.status}`);
+  return 'Подключение работает';
+});
+```
+
+Возвращённая строка показывается человеку зелёным, брошенная ошибка — красным.
+Отказ здесь не поломка: «не удалось подключиться» — законный ответ кнопки
+«проверить подключение», и падать из-за него нельзя, человек нажал именно
+затем, чтобы это узнать.
+
+Рабочий пример со всем сразу — [examples/feeds-plugin](../../examples/feeds-plugin):
+разделы, условное поле, две кнопки, задача по расписанию, инструмент и вклад в
+промпт, всё без единой зависимости.
+
+## Как не сжечь бюджет пользователя
+
+Это главное, ради чего Axon вообще существует, и плагин может всё испортить.
+
+**Редкий инструмент помечайте `deferred: true`.** Тогда его схема не грузится в
+контекст, пока модель сама не спросит. Пять инструментов с подробными схемами —
+это несколько тысяч токенов в *каждом* запросе.
+
+**Длинный вывод кладите в `api.blobs.write`,** а модели отдавайте краткую
+сводку. Всё, что вернул инструмент, остаётся в истории разговора и
+переотправляется каждый ход.
+
+**`stability` у вклада в контекст выбирайте честно.** `stable` уходит в
+кэшируемый префикс промпта, `volatile` — в хвост. Изменчивый текст (время,
+курс, погода), положенный в `stable`, обнуляет кэш промпта на каждом ходу.
+Ошибка не видна глазом и стоит десятикратной цены запроса.
+
+**Длинные инструкции — это скилл, а не описание инструмента.** У скилла в
+контексте постоянно висит одна строка; тело модель читает сама, когда задача
+под него подходит.
+
+## С чего начать
+
+```bash
+axon plugin new ./мой-плагин
+```
+
+Три файла: манифест, код и описание. Плагин из заготовки сразу работает —
+поднимается, регистрирует инструмент и отвечает на кнопку, — так что первое, что
+вы увидите, это работающая вещь, а не пустой шаблон.
+
+## Настройки без ручного разбора
+
+`get` возвращает `unknown`, и на нём легко ошибиться: пустое поле превращается в
+`NaN`, а галочка из формы приходит строкой `"false"`, которая истинна. Для
+частых случаев есть готовое:
+
+```js
+api.settings.text('greeting', 'Привет')   // строка, пустая — умолчание
+api.settings.number('limit', 30)          // число, негодное — умолчание
+api.settings.flag('notify', false)        // «false» из формы это ложь
+api.settings.lines('urls')                // многострочное поле как список
+```
+
+## Как поставить свой плагин
+
+**Из приложения:** Плагины → «Установить свой» в правом верхнем углу. Одно поле,
+куда кладут ссылку на репозиторий, и кнопка для архива. Готовые плагины берут
+из соседней вкладки «Каталог», а MCP-серверы подключают во вкладке «MCP».
+
+Архив — обычный `.zip`: тот, что отдаёт «Download ZIP» на гитхабе, или
+сделанный из папки проводником. Обёрточную папку внутри искать не надо, ядро
+найдёт `axon.plugin.json` само. `.tar.gz` тоже принимается.
+
+**Пока пишете плагин**, удобнее подключить папку по месту — тогда правки видны
+сразу, без пересборки архива:
+
+```bash
+axon plugin link ./мой-плагин     # подключить папку как есть
+axon plugin logs мой-плагин       # что он печатает
+```
+
+## Как это работает внутри
+
+Каждый плагин запускается **отдельным процессом**. Бесконечный цикл, утечка
+памяти или `process.exit()` внутри плагина убивают только его: ядро видит
+падение, снимает регистрацию его инструментов и продолжает работать.
+
+Обратная сторона — всё общение с ядром асинхронное и проходит через
+сериализуемые сообщения. Возвращать из `execute` можно только то, что
+переживёт `JSON.stringify`.
+
+Песочницы при этом нет: процесс работает с правами пользователя. `permissions`
+в манифесте — это информированное согласие, а не ограничение. Чужой
+непроверенный код правильнее подключать как MCP-сервер.

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+/**
+ * @axon-assistant/plugin-sdk — то, что нужно, чтобы написать плагин Axon.
+ *
+ * Пакет почти целиком состоит из типов и не тянет ни одной зависимости. Это
+ * не аскеза: `api` приезжает аргументом в `activate`, поэтому в рантайме
+ * плагину импортировать из SDK нечего. Плагин без единой зависимости — папка,
+ * которую можно склонировать и запустить, а не проект, который надо сначала
+ * собрать.
+ *
+ * ```js
+ * export async function activate(api) {
+ *   await api.tools.register({
+ *     name: 'ping',
+ *     title: 'Пинг',
+ *     description: 'Проверить, что плагин жив. Вызывай, если просят проверить связь.',
+ *     tier: 'safe',
+ *     parameters: { type: 'object', properties: {} },
+ *     execute: async () => 'понг',
+ *   });
+ * }
+ * ```
+ */
+/** Уровень риска. Определяет, спросят ли разрешение и кому инструмент доступен. */
+export type RiskTier = 'safe' | 'sensitive' | 'dangerous';
+export interface Fact {
+    id: string;
+    key: string;
+    value: string;
+    origin: 'user' | 'inferred';
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PluginToolContext {
+    conversationId: string;
+    runId: string;
+    /** Отменяется, когда пользователь останавливает прогон. */
+    signal: AbortSignal;
+    /**
+     * Спросить разрешение посреди выполнения. Возвращает решение; если ответить
+     * некому (фоновая задача, клиент без прав) — false.
+     */
+    requestPermission(reason: string): Promise<boolean>;
+}
+export interface PluginTool {
+    /**
+     * Короткое имя. Ядро добавит префикс с id плагина: `search` плагина `github`
+     * модель увидит как `github_search`. Поэтому два плагина с одинаково
+     * названными инструментами не затирают друг друга.
+     */
+    name: string;
+    title: string;
+    /** Для модели — «когда вызывать», а не только «что делает». */
+    description: string;
+    tier: RiskTier;
+    /** JSON Schema аргументов. Обычный объект: zod здесь не нужен. */
+    parameters: Record<string, unknown>;
+    /**
+     * Не грузить схему в контекст, пока модель сама не спросит. Для редких
+     * инструментов — прямая экономия на каждом запросе.
+     */
+    deferred?: boolean;
+    /** Свой потолок вывода в символах. По умолчанию 2000. */
+    previewLimit?: number;
+    execute(args: Record<string, unknown>, ctx: PluginToolContext): Promise<string | {
+        text: string;
+        mime?: string;
+    }>;
+}
+export interface PluginModelInfo {
+    id: string;
+    name?: string;
+    contextTokens?: number;
+    inputPerMTok?: number;
+    outputPerMTok?: number;
+}
+export type PluginChatEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'tool_call';
+    call: {
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+} | {
+    type: 'usage';
+    usage: {
+        inputTokens: number;
+        cachedInputTokens?: number;
+        cacheWriteTokens?: number;
+        outputTokens: number;
+        costUsd?: number;
+        provider: string;
+        model: string;
+    };
+} | {
+    type: 'done';
+    stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'refusal' | 'cancelled';
+};
+export interface PluginProvider {
+    id: string;
+    label: string;
+    supportsPromptCache: boolean;
+    models: PluginModelInfo[];
+    chat(request: unknown, signal: AbortSignal): AsyncIterable<PluginChatEvent>;
+}
+export interface PluginContributeInput {
+    conversationId: string;
+    /** Последнее сообщение пользователя — для поиска по релевантности. */
+    userText: string;
+}
+/**
+ * Куда попадёт вклад в промпт:
+ *
+ * - `stable` — в системный блок, то есть в кэшируемый префикс;
+ * - `volatile` — в самый хвост, после всей истории.
+ *
+ * Ошибка не видна глазом, но дорога: изменчивый текст (время, курс, погода) в
+ * стабильной части обнуляет кэш промпта на каждом ходу.
+ */
+export type PluginStability = 'stable' | 'volatile';
+export interface PluginJournalEntry {
+    seq: number;
+    at: string;
+    event: {
+        type: string;
+    } & Record<string, unknown>;
+}
+export interface PluginApi {
+    readonly id: string;
+    /** Корень плагина. Только чтение: обновление перезаписывает папку. */
+    readonly dir: string;
+    /** Личная папка для данных плагина. Переживает обновление. */
+    readonly dataDir: string;
+    readonly log: {
+        debug(message: string, data?: Record<string, unknown>): void;
+        info(message: string, data?: Record<string, unknown>): void;
+        warn(message: string, data?: Record<string, unknown>): void;
+        error(message: string, data?: Record<string, unknown>): void;
+    };
+    readonly settings: {
+        all(): Record<string, unknown>;
+        get<T = unknown>(key: string): T | undefined;
+        set(values: Record<string, unknown>): Promise<void>;
+        onChange(listener: (values: Record<string, unknown>) => void): void;
+        /**
+         * Прочитать с приведением типа и умолчанием.
+         *
+         * `get` возвращает `unknown`, и каждый плагин начинался с десятка строк
+         * ручного разбора: `Number(api.settings.get('limit') ?? 30)`. Мелочь,
+         * которая встречается в каждом плагине по нескольку раз, — а значит и
+         * ошибаются в ней регулярно: пустое поле превращается в `NaN`, галочка
+         * из формы приходит строкой `"false"` и оказывается истиной.
+         *
+         * Умолчание обязательно: настройка, которую человек не заполнил, — это
+         * норма, а не исключительная ситуация.
+         */
+        text(key: string, fallback: string): string;
+        number(key: string, fallback: number): number;
+        flag(key: string, fallback: boolean): boolean;
+        /** Многострочное поле как список: пустые строки отброшены, края обрезаны. */
+        lines(key: string): string[];
+    };
+    readonly tools: {
+        register(tool: PluginTool): Promise<void>;
+        unregister(name: string): Promise<void>;
+    };
+    readonly context: {
+        /** Добавить абзац в промпт. `null` из функции — в этот раз ничего не добавлять. */
+        contribute(name: string, stability: PluginStability, contribute: (input: PluginContributeInput) => Promise<string | null> | string | null): Promise<void>;
+        remove(name: string): Promise<void>;
+    };
+    readonly providers: {
+        register(provider: PluginProvider): Promise<void>;
+        unregister(id: string): Promise<void>;
+    };
+    readonly skills: {
+        /** Добавить скилл на лету. Обычно они просто лежат файлами в папке из манифеста. */
+        add(skill: {
+            name: string;
+            description: string;
+            body: string;
+        }): Promise<void>;
+    };
+    readonly jobs: {
+        /** Обработчик задачи из манифеста. Расписанием владеет ядро. */
+        on(name: string, run: () => Promise<void> | void): void;
+    };
+    readonly actions: {
+        /**
+         * Обработчик кнопки со страницы настроек — той, что объявлена в манифесте
+         * в `actions`. Возвращённая строка показывается человеку; брошенная
+         * ошибка тоже показывается, но как неудача.
+         *
+         * Это единственный способ дать плагину что-то делать по нажатию, и
+         * намеренно узкий: плагин отвечает текстом, а рисует приложение. Пусти
+         * его рисовать самому — и код плагина окажется в окне с полным доступом
+         * к ядру, ровно там, откуда его убрали отдельным процессом.
+         */
+        on(name: string, run: () => Promise<string | void> | string | void): void;
+    };
+    /**
+     * Спросить модель, настроенную у человека.
+     *
+     * До этого плагин умел быть провайдером, но не умел им пользоваться: автору
+     * суммаризатора или переводчика приходилось заводить собственный ключ,
+     * хотя у ядра он уже есть и настроен. Расход при этом уходил мимо счётчика
+     * и мимо потолка, то есть человек платил и не видел за что.
+     *
+     * Один вопрос без истории и без инструментов. Это не агент — если плагину
+     * нужен агент, он для этого и существует сам по себе.
+     */
+    readonly model: {
+        ask(input: {
+            prompt: string;
+            system?: string;
+            maxTokens?: number;
+        }): Promise<string>;
+    };
+    /**
+     * Сказать человеку.
+     *
+     * Плагин, который следит за чем-то, до этого не мог дать о себе знать: он
+     * ждал, пока агента спросят. Уведомление показывает тот клиент, который
+     * сейчас на связи, — у ядра экрана нет.
+     *
+     * Мера, а не право: уведомление, приходящее часто, выключают вместе с
+     * плагином.
+     */
+    notify(title: string, body?: string): Promise<void>;
+    /**
+     * Сказать о себе.
+     *
+     * Состояние плагина ядро выводит из состояния процесса: жив — значит
+     * работает. Плагин, у которого отвалился внешний сервер, при этом живее
+     * всех живых и молчит. Пометкой он может сказать, что дела плохи, и человек
+     * увидит это в списке, а не будет гадать, почему инструмент не отвечает.
+     */
+    readonly status: {
+        set(note: string, failed?: boolean): Promise<void>;
+        clear(): Promise<void>;
+    };
+    /**
+     * Поиск по переписке — тот же, что у агента.
+     *
+     * Плагин видит факты, но не разговоры. Тому, кто хочет опереться на
+     * контекст, взять его было неоткуда.
+     */
+    readonly history: {
+        search(query: string, limit?: number): Promise<Array<{
+            messageId: string;
+            conversationId: string;
+            role: string;
+            snippet: string;
+        }>>;
+    };
+    readonly journal: {
+        /** Требует права `journal` в манифесте — иначе события просто не придут. */
+        on(listener: (entry: PluginJournalEntry) => void): void;
+    };
+    readonly memory: {
+        facts(): Promise<Fact[]>;
+        remember(key: string, value: string): Promise<void>;
+    };
+    readonly blobs: {
+        /** Положить большой вывод в хранилище ядра вместо того, чтобы гнать его в модель. */
+        write(input: {
+            data: Uint8Array | string;
+            mime: string;
+            name?: string;
+        }): Promise<{
+            blobId: string;
+            bytes: number;
+        }>;
+    };
+}
+/** Это плагин экспортирует из файла, указанного в `main`. */
+export interface PluginModule {
+    activate(api: PluginApi): Promise<void> | void;
+    deactivate?(): Promise<void> | void;
+}
+/**
+ * Помощники для вывода типов. Ничего не делают в рантайме — существуют только
+ * затем, чтобы редактор подсказывал поля, не заставляя писать аннотации.
+ */
+export declare function defineTool(tool: PluginTool): PluginTool;
+export declare function definePlugin(module: PluginModule): PluginModule;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,33 @@
+/**
+ * @axon-assistant/plugin-sdk — то, что нужно, чтобы написать плагин Axon.
+ *
+ * Пакет почти целиком состоит из типов и не тянет ни одной зависимости. Это
+ * не аскеза: `api` приезжает аргументом в `activate`, поэтому в рантайме
+ * плагину импортировать из SDK нечего. Плагин без единой зависимости — папка,
+ * которую можно склонировать и запустить, а не проект, который надо сначала
+ * собрать.
+ *
+ * ```js
+ * export async function activate(api) {
+ *   await api.tools.register({
+ *     name: 'ping',
+ *     title: 'Пинг',
+ *     description: 'Проверить, что плагин жив. Вызывай, если просят проверить связь.',
+ *     tier: 'safe',
+ *     parameters: { type: 'object', properties: {} },
+ *     execute: async () => 'понг',
+ *   });
+ * }
+ * ```
+ */
+/**
+ * Помощники для вывода типов. Ничего не делают в рантайме — существуют только
+ * затем, чтобы редактор подсказывал поля, не заставляя писать аннотации.
+ */
+export function defineTool(tool) {
+    return tool;
+}
+export function definePlugin(module) {
+    return module;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA8QH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAgB;IACzC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@axon-assistant/plugin-sdk",
+  "version": "2026.8.23",
+  "comment:version": "Заглушка. Настоящий номер проставляется из git-тега при публикации: см. scripts/release-npm.mjs. Версия, которую правят руками, рано или поздно расходится с тем, что опубликовано.",
+  "description": "Типы для написания плагинов Axon",
+  "keywords": [
+    "axon",
+    "plugin",
+    "ai",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bigtaed-sys/axon.git",
+    "directory": "packages/plugin-sdk"
+  },
+  "homepage": "https://github.com/bigtaed-sys/axon#readme",
+  "bugs": "https://github.com/bigtaed-sys/axon/issues",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  }
+}