optimatica-meters

TypeScript SDK для распознавания счётчиков ЖКХ по фото. HTTP-клиент, типы и глобальная конфигурация — ядро monorepo.

Установка

npm install optimatica-meters

Нет runtime-зависимостей — только встроенные fetch и FormData.

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

import { analyzeMeterPhoto, configureZhkhSdk } from 'optimatica-meters'

configureZhkhSdk({
  apiKey: 'eyJhbGci...', // JWT-токен
})

const result = await analyzeMeterPhoto(file)

if (result.success) {
  console.log(result.meter.serialNumber, result.meter.currentReading)
}

Экспорты

| Имя | Описание | |-----|----------| | analyzeMeterPhoto | Отправка одного фото на API | | analyzeMeterPhotos | Отправка нескольких фото за один запрос | | configureZhkhSdk | Глобальный конфиг (apiKey) | | getZhkhConfig | Текущий конфиг | | resolveSdkOptions | Слияние пропсов и глобального конфига | | API_ENDPOINT | URL эндпоинта, зашитый при сборке | | ZhkhApiError | Ошибка HTTP / валидации | | METER_TYPE_LABELS | Русские названия типов счётчиков |

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

import { configureZhkhSdk } from 'optimatica-meters'

configureZhkhSdk({
  apiKey: 'eyJhbGci...', // опционально — можно передать в каждый вызов
})

Эндпоинт API

URL эндпоинта зашивается в SDK на этапе сборки из переменной окружения OPTIMATICA_API_URL. Если переменная не задана, используется production по умолчанию:

https://meters-api-prod.nyc-1.optimatica.pro/api/meters/analyze

Чтобы зафиксировать другой эндпоинт, задайте переменную при сборке пакета:

OPTIMATICA_API_URL="https://staging.example.com/api/meters/analyze" npm run build

В рантайме URL не настраивается.

analyzeMeterPhoto

import { analyzeMeterPhoto } from 'optimatica-meters'

// Browser
await analyzeMeterPhoto(file)

// React Native
await analyzeMeterPhoto({
  uri: 'file:///path/to/photo.jpg',
  name: 'meter.jpg',
  type: 'image/jpeg',
})

// С переопределением ключа и отменой запроса
await analyzeMeterPhoto(file, {
  apiKey: 'eyJhbGci...',
  signal: abortController.signal,
})

analyzeMeterPhotos (несколько фото)

Распознавание нескольких счётчиков за один запрос (до 10 фото). Возвращает массив результатов в порядке переданных изображений.

import { analyzeMeterPhotos } from 'optimatica-meters'

const results = await analyzeMeterPhotos([file1, file2, file3])

for (const result of results) {
  if (result.success) console.log(result.meter.serialNumber)
  else console.warn(result.error)
}

Эндпоинт принимает поле image один или несколько раз и всегда отдаёт { results: AnalyzeMeterResponse[] }; при единственном фото результат дублируется наверх, поэтому analyzeMeterPhoto остаётся обратно совместимым.

Типы изображений

type AnalyzeMeterImage = File | Blob | ReactNativeImageAsset

Поддерживаются браузерные File/Blob и React Native-ассеты { uri, name?, type? }.

Документация

Полная документация и API Playground: apps/docs.