seedkit_module_api 0.0.3

SeedKit API module with Dio client helpers, token refresh, pagination, cache and error handling.

seedkit_module_api

Модуль API для SeedKit-приложений. Пакет объединяет настройку Dio, базовый HTTP-клиент, обновление токенов, обработку ошибок, пагинацию, offline-cache и нормализацию JSON-полей.

Возможности

• глобальная настройка API через ApiModule;
• базовый ApiClient с методами get, post, put, patch, delete, upload, download и batch;
• автоматическая подстановка auth-заголовков и обновление токена при 401;
• поток статуса токена через getTokenStream и TokenStatusEnum;
• единый формат ошибок через BaseException и ErrorHandler;
• модель пагинации PaginationModel;
• проверка подключения через ConnectivityService;
• DioStorageInterceptor для cache/offline-сценариев;
• MockInterseptor для локальных mock-ответов;
• схема JsonFieldAlias для нормализации разных названий JSON-полей.

Установка

dependencies:
  seedkit_module_api: ^0.0.1

Перед использованием клиента настройте модуль:

ApiModule(
  baseApiUrl: 'https://example.com/api/',
  storaPath: appDocumentsPath,
  deviceId: deviceId,
  platform: 'android',
);

ConnectivityService();

Локализация Ошибок

Пакет использует seedkit_locale для текстов стандартных ошибок. ARB-файлы пакета лежат в assets/l10n/, поэтому основное приложение должно запускать генерацию локализации через seedkit_locale:

dart run seedkit_locale:generate

После этого зарегистрируйте SeedKitLocale.seedkitDelegate в приложении.

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

Создайте свой клиент от ApiClient:

class AppApiClient extends ApiClient {
  AppApiClient({super.interceptors});

  Future<Either<BaseException, User>> getUser(String id) {
    return get(
      '/users/$id',
      mapper: (json) => User.fromJson(json),
    );
  }
}

Подписка на состояние токена:

api.getTokenStream.listen((status) {
  switch (status) {
    case TokenStatusEnum.access:
      break;
    case TokenStatusEnum.process:
      break;
    case TokenStatusEnum.empty:
      break;
  }
});

Пагинация:

final pagination = PaginationModel();

final result = await api.batch(
  '/users',
  pagination: pagination,
  mapper: (json) => UsersPage.fromJson(json),
);

Нормализация JSON-полей:

final result = await api.get(
  '/profile',
  jsonSchemas: const [
    JsonFieldAlias(aliases: ['name', 'full_name', 'displayName']),
  ],
  mapper: (json) => Profile.fromJson(json),
);

Mock-ответы:

final api = AppApiClient(
  interceptors: [
    MockInterseptor(
      dataSetter: (_) => {'id': '1', 'name': 'Test'},
    ),
  ],
);