bridge

@vkma.dev/bridge — независимый VK Bridge для VK Mini Apps. Классический API (send / subscribe / supportsAsync / …), встроенный observability-tap, таймаут и abort на каждый send и настраиваемая политика request_id.

Типы приходят из @vkma.dev/bridge-schema — каталог всех событий платформы как данные, с открытым интерфейсом для собственных событий.

npm install @vkma.dev/bridge

Использование

import bridge from "@vkma.dev/bridge";

await bridge.send("VKWebAppInit");
const user = await bridge.send("VKWebAppGetUserInfo");

// каждый subscribe возвращает свою функцию отписки
const off = bridge.subscribe(event => {
    // event.detail.type / event.detail.data, каждое событие от хоста
});

Или собирай изолированные инстансы (свой tap, своё состояние pairing’а):

import { createVKBridge } from "@vkma.dev/bridge";

const bridge = createVKBridge("1.0.0", {
    // строка версии сообщается web-хосту
    requestId: { generator: sequence => `req-${sequence}` },
});

Сверх классического API

Всё живёт на инстансе, без лишних импортов:

// каждый исходящий send и входящее событие, всегда включены,
// replay для опоздавших подписчиков
const off = bridge.onSend(event => log(event.name, event.payload));
const off2 = bridge.onEvent(event => log(event.name, event.ok));

// контроль на каждый send
await bridge.send("VKWebAppGetUserInfo", undefined, { timeout: 5000 });
await bridge.send("VKWebAppShowWallPostBox", props, { signal: controller.signal });

// политика request_id (по умолчанию: авто-инъекция __vkma_<n>,
// именно на ней работает pairing ответов)
createVKBridge("1.0.0", { requestId: { inject: false } });

Импорта пакета достаточно, чтобы devtools видел трафик моста: инстанс по умолчанию публикует хэндл на globalThis.__vkmaDevtoolsBridge (подробности — в tap).

Типы и кастомные события

Все типы полезных нагрузок и три каталога-мапы реэкспортируются здесь. Чтобы научить мост своим событиям (или событиям прокси-бэкенда), расширяй schema-пакет — и send, subscribe и все потребители типов подхватят:

declare module "@vkma.dev/bridge-schema" {
    interface RequestPropsMap {
        VKWebAppMyCustomMethod: { foo: string };
    }
    interface ReceiveDataMap {
        VKWebAppMyCustomMethodResult: { bar: number };
    }
    interface ReceiveEventMap {
        VKWebAppMyCustomMethod: {
            result: "VKWebAppMyCustomMethodResult";
            failed: "VKWebAppMyCustomMethodFailed";
        };
    }
}

Правила живут в @vkma.dev/bridge-schema. Аугментируй корень schema-пакета, расширяй, но не переопределяй.

Транспорты

Web (iframe postMessage с конвертом vk-connect), Android WebView, iOS WebView и React Native WebView, с приёмными листенерами message / VKWebAppEvent в придачу.

Подробнее

• События и подписки — паринг ответов, ошибки, subscribe
• Таймауты и отмена — timeout, AbortSignal, повторы
• Инстансы и request_id — createVKBridge и изоляция
• Tap и devtools — onSend/onEvent и replay-буфер
• Транспорты — vk-connect конверт, WebView’ы, supportsAsync

Ссылки

• npm: @vkma.dev/bridge