MiniApp SDK

SDK для Mini App внутри контейнера Super App. Обеспечивает коммуникацию между веб-приложением и нативной стороной (Android, iOS, iframe) через единый bridge-интерфейс.

В standalone-режиме (обычный браузер) все вызовы — no-op, приложение не падает.

Установка

npm install @alfalab/miniapp-sdk

Быстрый старт

import { MiniAppSDK } from '@alfalab/miniapp-sdk';

const sdk = new MiniAppSDK();

// Настройка навбара
await sdk.ui.navbar.configure({
    title: 'Профиль',
    showBackButton: true,
    size: 'regular',
});

// Показать таббар и (опционально) выбрать вкладку
await sdk.ui.tabbar.show({ selectedId: 'home' });

// Подписка на кнопку «Назад»
const unsubscribe = sdk.navigation.backButton.onPress(() => history.back());

Конфигурация

const sdk = new MiniAppSDK({
    defaultTimeout: 10000, // таймаут для call-запросов (мс), по умолчанию 10000
    transport: 'android', // явное указание транспорта, по умолчанию — автоопределение
    hostOrigin: 'https://app.example.com', // обязателен для iframe
    allowedOrigins: [], // дополнительные разрешённые origin'ы для iframe
    logger: new ConsoleLogger(), // по умолчанию — NullLogger (no-op)
});

API

sdk.ui

| Метод | Описание | | -------------------------------- | -------------------------------------------------------------- | | ui.tabbar.hide() | Скрывает таббар | | ui.tabbar.show(config) | Показывает таббар и может выбрать вкладку через selectedId | | ui.tabbar.onItemPress(handler) | Подписка на тап по иконке таббара. Возвращает функцию отписки | | ui.navbar.configure(config) | Устанавливает заголовок, подзаголовок, кнопку «Назад» и размер | | ui.nativeLoader.show() | Показывает нативный лоадер | | ui.nativeLoader.hide() | Скрывает нативный лоадер |

Типы конфигурации:

type TabbarConfig = {
    selectedId: string | null; // null — не менять текущую вкладку
};

type NavbarConfig = {
    title: string;
    subtitle?: string | null;
    showBackButton: boolean;
    size: 'regular' | 'large';
};

sdk.navigation

| Метод | Описание | | ---------------------------------------- | ------------------------------------------------------ | | navigation.backButton.onPress(handler) | Подписка на кнопку «Назад». Возвращает функцию отписки |

sdk.invoke (escape hatch)

Прямой вызов action'а — только для прототипирования или тестирования до выхода релиза. В продакшне используйте готовые модули.

const result = await sdk.invoke<MyResult>('custom.action', { id: 1 }, { kind: 'call' });

// fire-and-forget — если нативная сторона не возвращает ответ
await sdk.invoke('custom.action', payload, { kind: 'send' });

sdk.on (escape hatch)

Подписка на произвольное событие от нативной стороны — только если нужного события ещё нет в SDK.

const unsubscribe = sdk.on('deeplink.open', (data) => {
    console.log(data);
});

sdk.use — middleware

sdk.use(async (ctx, next) => {
    console.log('->', ctx.action, ctx.payload);
    const result = await next();
    console.log('<-', ctx.action, result);
    return result;
}).use(analyticsMiddleware);

sdk.destroy

sdk.destroy(); // реджектит pending-запросы, снимает подписки, отключает транспорт

Обработка ошибок

import {
    isTimeoutError,
    isAbortedError,
    isRemoteError,
    isDestroyedError,
    isTransportError,
} from '@alfalab/miniapp-sdk';

try {
    await sdk.invoke('custom.action');
} catch (error) {
    if (isTimeoutError(error)) console.log('таймаут:', error.timeoutMs);
    if (isAbortedError(error)) console.log('отменён');
    if (isRemoteError(error)) console.log('ошибка натива:', error.remoteCode, error.details);
    if (isDestroyedError(error)) console.log('SDK уничтожен');
    if (isTransportError(error)) console.log('ошибка транспорта');
}

Declaration merging

Расширение типов для кастомных action'ов и событий:

declare module '@alfalab/miniapp-sdk' {
    interface ActionContract {
        'payments.charge': { payload: { amount: number }; result: { transactionId: string } };
    }

    interface EventContract {
        'deeplink.open': { url: string };
    }
}

Логирование

import { ConsoleLogger } from '@alfalab/miniapp-sdk';

// Для разработки
const sdk = new MiniAppSDK({ logger: new ConsoleLogger() });

// Кастомный логгер
const sdk = new MiniAppSDK({
    logger: {
        debug: (msg, ...args) => myLogger.debug(msg, ...args),
        info: (msg, ...args) => myLogger.info(msg, ...args),
        warn: (msg, ...args) => myLogger.warn(msg, ...args),
        error: (msg, ...args) => myLogger.error(msg, ...args),
    },
});