JavaScript Client Library (CDN SDK)

Browser-first JavaScript client for the Orthodox Calendar API.

CDN usage

<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>

Construction

type Lang = 'ru' | 'en';

type ClientOptions = {
  baseUrl?: string;          // default: https://api.ispovednik.org/api/v1
  defaultLang?: Lang;        // default: 'ru'
  defaultType?: number;      // optional default saints type filter
  timeoutMs?: number;        // default: 15000
  fetchImpl?: typeof fetch;  // override for tests / SSR
  onRequest?: (ctx: { url: string; init: RequestInit }) => void;
  onResponse?: (ctx: { url: string; status: number }) => void;
  normalize?: boolean;       // default: false (see “Normalization”)
  dedupe?: boolean;          // default: true (in-flight request memoization)
  cacheTtlMs?: number;       // default: 0 (disabled)
  maxCacheEntries?: number;  // default: 200
};

client = OrthodoxCalendarApi.createClient(options);

All endpoint methods accept:

type RequestOptions = {
  lang?: Lang;
  type?: number;        // only where API supports it
  signal?: AbortSignal;
  timeoutMs?: number;
  raw?: boolean;        // bypass normalization (if enabled)
};

Endpoint coverage (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) → splits/merges range calls (max 366 days per request)

Calendar day objects include weekAfterPentecost as an always-present numeric field.

• 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) → splits/merges range calls (max 100 years per request)

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

Errors

SDK throws ApiError:

• status (HTTP status, or 0 for network/timeout errors)
• url
• message (server error.message when available)
• details (server error.details when available)
• code (server error.code when available)

Normalization

By default, SDK returns responses as-is (“raw”).

If you enable normalize: true, /saints/* responses are converted to camelCase:

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

You can also call helpers directly:

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

Convenience helpers

• OrthodoxCalendarApi.unwrapDay(envelope) → returns the first day object from envelope.data
• OrthodoxCalendarApi.unwrapDataMap(envelope) → returns 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 supports: feast, event, saint, icon_of_mother_of_god, memorial, week.