pulat
Repositories Projects Packages
8
 Public activity Starred repositories

@sotuvcore/exchange-rate (0.2.0)

Published 2026-07-29 15:17:24 +05:00 by pulat

Installation

@sotuvcore:registry=
npm install @sotuvcore/exchange-rate@0.2.0
"@sotuvcore/exchange-rate": "0.2.0"

About this package

@sotuvcore/exchange-rate

Модуль курсов валют для Sotuza (Medusa v2). Тянет курсы из ЦБ РУЗ (cbu.uz), кеширует, обновляет по расписанию, fallback на stale при недоступности API.

Возможности

  • CBU.UZ клиент — проверенные endpoints, retry только на 5xx, timeout 10s, нормализация Rate/Nominal
  • Service — in-memory cache, refreshRate / refreshAll / convertToUzs / getCachedRate
  • Scheduled job — cron 5 */4 * * * (каждые 4 часа в :05), overridable через EXCHANGE_RATE_CRON
  • Порог изменения — обновляет курс только если разница >0.5% (снижает шум)
  • Fallback на stale — при недоступности CBU возвращает последний известный курс до 48 часов давности
  • Unit-тесты — покрытие клиента + service (10+ кейсов, включая retry, fallback, threshold)

Установка

pnpm add @sotuvcore/exchange-rate

Подключение в medusa-config.ts (apps/sotuza)

modules: [
  // ...
  {
    resolve: '@sotuvcore/exchange-rate',
    options: {
      minChangeThreshold: 0.005,   // 0.5%
      maxStaleAgeHours: 48,
      // cbuBaseUrl: 'https://cbu.uz',  // override для тестов
    },
  },
],

Job

Создать в apps/sotuza/src/jobs/refresh-exchange-rate.ts:

export { default, config } from '@sotuvcore/exchange-rate/jobs/refresh-rate'

Medusa scheduler автоматически подхватит job из этой директории и запустит по cron.

Переопределить набор валют:

EXCHANGE_RATE_CURRENCIES=USD,EUR,RUB,KZT

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

const svc = container.resolve('exchangeRateModule')

await svc.refreshRate('USD')       // тянет с CBU.UZ, кладёт в cache
const rate = svc.getCachedRate('USD') // sync доступ

const uzs = svc.convertToUzs(10, 'USD') // 10 USD → UZS (по кешу)

API ЦБ РУЗ

Проверенные endpoints (2026-07-01):

  • GET https://cbu.uz/oz/arkhiv-kursov-valyut/json/ — все валюты
  • GET https://cbu.uz/oz/arkhiv-kursov-valyut/json/USD/ — одна валюта
  • GET https://cbu.uz/oz/arkhiv-kursov-valyut/json/USD/YYYY-MM-DD/ — исторический курс

Тесты

pnpm test           # unit
pnpm test:watch     # watch mode

Roadmap

  • v0.2 — DML модель ExchangeRate + persistence в Postgres (сейчас in-memory)
  • v0.3 — per-tenant courses (для multi-tenant Sotuvcore Shop)
  • v0.4 — REST endpoint для storefront/MiniApp (GET /store/exchange-rate/:ccy)
  • v0.5 — интеграция с @sotuvcore/pricing-usd-uzs (пересчёт цен товаров)

Dependencies

Development dependencies

ID Version
@medusajs/framework ^2.17.0
@medusajs/types ^2.17.0
typescript ^5.5.0
vitest ^2.0.0

Peer dependencies

ID Version
@medusajs/framework ^2.17.0
Details
npm
2026-07-29 15:17:24 +05:00
13
UNLICENSED
latest
12 KiB
Assets (1)
exchange-rate-0.2.0.tgz 12 KiB
Versions (1) View all
0.2.0 2026-07-29