JavaScript клиентская библиотека (CDN SDK)

Клиентская JavaScript-библиотека для API Православного календаря, ориентированная на браузер.

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

<script src="https://api.ispovednik.org/cdn/orthodox-calendar-api.min.js"></script>
<script type="module">
  const client = OrthodoxCalendarApi.createClient({
    baseUrl: 'https://api.ispovednik.org/api/v1',
    defaultLang: 'ru',
  });

  async function run() {
    const res = await client.calendar.day('2027-06-19');
    console.log(res.data['2027-06-19']);
  }

  run().catch(console.error);
</script>

Создание клиента

type Lang = 'ru' | 'en';

type ClientOptions = {
  baseUrl?: string;          // по умолчанию: https://api.ispovednik.org/api/v1
  defaultLang?: Lang;        // по умолчанию: 'ru'
  defaultType?: number;      // опциональный фильтр типа святых
  timeoutMs?: number;        // по умолчанию: 15000
  fetchImpl?: typeof fetch;  // переопределение для тестов / SSR
  onRequest?: (ctx: { url: string; init: RequestInit }) => void;
  onResponse?: (ctx: { url: string; status: number }) => void;
  normalize?: boolean;       // по умолчанию: false (см. “Нормализация”)
  dedupe?: boolean;          // по умолчанию: true (дедупликация параллельных запросов)
  cacheTtlMs?: number;       // по умолчанию: 0 (выкл.)
  maxCacheEntries?: number;  // по умолчанию: 200
};

client = OrthodoxCalendarApi.createClient(options);

Все методы поддерживают:

type RequestOptions = {
  lang?: Lang;
  type?: number;        // только для эндпоинтов, где поддерживается
  signal?: AbortSignal;
  timeoutMs?: number;
  raw?: boolean;        // отключить нормализацию (если включена)
};

Покрытие эндпоинтов (v1)

• client.calendar.day(date, opts) → GET /calendar/day/{YYYY-MM-DD}
• client.calendar.month(year, month, opts) → GET /calendar/month/{YYYY}/{M}
• client.calendar.year(year, opts) → GET /calendar/year/{YYYY}
• client.calendar.range(from, to, opts) → GET /calendar/range?from=...&to=...
• client.calendar.rangeChunked(from, to, opts) → разбивка/слияние запросов (макс. 366 дней на запрос)

Объекты дня календаря включают weekAfterPentecost как всегда присутствующее числовое поле.

• client.saints.day(date, opts) → GET /saints/day/{YYYY-MM-DD}

• client.saints.month(year, month, opts) → GET /saints/month/{YYYY}/{M}

• client.saints.year(year, opts) → GET /saints/year/{YYYY}

• client.saints.range(from, to, opts) → GET /saints/range?from=...&to=...

• client.saints.rangeChunked(from, to, opts)

• client.fasting.day(date, opts) → GET /fasting/day/{YYYY-MM-DD}

• client.fasting.month(year, month, opts) → GET /fasting/month/{YYYY}/{M}

• client.fasting.year(year, opts) → GET /fasting/year/{YYYY}

• client.fasting.range(from, to, opts) → GET /fasting/range?from=...&to=...

• client.fasting.rangeChunked(from, to, opts)

• client.movable.day(date, opts) → GET /movable/day/{YYYY-MM-DD}

• client.movable.year(year, opts) → GET /movable/year/{YYYY}

• client.movable.range(fromYear, toYear, opts) → GET /movable/range?from=YYYY&to=YYYY

• client.movable.rangeChunked(fromYear, toYear, opts) → разбивка/слияние запросов (макс. 100 лет на запрос)

• client.memorial.year(year, opts) → GET /memorial/year/{YYYY}

Ошибки

SDK бросает ApiError:

• status (HTTP-статус, или 0 для ошибок сети/таймаута)
• url
• message (поле error.message из ответа сервера, если есть)
• details (поле error.details из ответа сервера, если есть)
• code (поле error.code из ответа сервера, если есть)

Нормализация

По умолчанию SDK возвращает ответы “как есть”.

Если включить normalize: true, ответы /saints/* будут приведены к camelCase:

• gregorian_date → gregorianDate
• day_of_week → dayOfWeek
• julian_day + julian_month → julianDay + julianMonth

Можно использовать вспомогательную функцию напрямую:

const raw = await client.saints.day('2026-01-01', { raw: true });
const normalized = OrthodoxCalendarApi.normalizeSaintsEnvelope(raw);

Удобные вспомогательные функции

• OrthodoxCalendarApi.unwrapDay(envelope) → возвращает первый объект дня из envelope.data
• OrthodoxCalendarApi.unwrapDataMap(envelope) → возвращает envelope.data
• client.filterEvents(events, { kind })
• client.getWeekEvents(day) / client.getFeastEvents(day) / client.getEventEvents(day) / client.getSaintEvents(day) / client.getIconOfMotherOfGodEvents(day)
• client.filterSaints(day, { typeId })

CalendarEvent.kind поддерживает значения: feast, event, saint, icon_of_mother_of_god, memorial, week.