Официальный TypeScript SDK

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

Если apiKey не передан, клиент берёт OCCULT_API_KEY из переменных окружения. Создайте ключ — он показывается один раз, поэтому скопируйте его, прежде чем уйти со страницы.

import { OccultApi } from "occult-api";

const occult = new OccultApi({ apiKey: process.env.OCCULT_API_KEY });

const sun = await occult.astro.sunrise({
  date_time: "2026-09-01T06:00:00+05:30",
  latitude: 26.9124,
  longitude: 75.7873,
  timezone_as_float: 5.5,
});

console.log(sun.sunrise, sun.sunset);

Методы повторяют URL

/api/astro/eclipse/next-solar/ — это occult.astro.eclipse.nextSolar(). Семь путей одновременно и эндпоинт, и родитель для других, поэтому они вызываемые объекты: работают и occult.astro.eclipse(), и occult.astro.eclipse.upcoming().

Имена полей ровно такие, как ждёт API: date_time, а не dateTime. Слоя преобразования нет — что вы пишете, то и уходит в запрос.

Один кредит, сколько ни спросите

Самое полезное, что стоит знать о ценах. Шесть расчётов в одном вызове стоят в шесть раз меньше, чем шесть отдельных вызовов.

// Six calculations, ONE credit. A call costs the same whether you
// ask for one key or twenty, so batch what the screen needs.
const panchang = await occult.astro.panchanga({
  ...place,
  keys: ["tithi", "nakshatra_segments", "yogam", "karana", "choghadiya", "rahu_kaalam"],
});

Эти имена типизированы для каждого эндпоинта. Панчанга принимает 57 имён, и одно неверное отклоняет весь запрос, поэтому SDK превращает такую опечатку в ошибку компиляции, а не в потраченный впустую вызов.

Ошибки, по которым удобно ветвиться

import { OccultApiError } from "occult-api";

try {
  await occult.astro.panchanga({ ...place, keys: ["tithi"] });
} catch (error) {
  if (error instanceof OccultApiError) {
    if (error.code === "insufficient_credits") await upgradePlan();
    if (error.code === "validation_error") console.log(error.fields);
    // error.retryable is false for anything a retry cannot fix
  }
}

Любой сбой — это OccultApiError со стабильным машинным кодом, так что вы ветвитесь по причине, а не разбираете текст, который могут переформулировать. Временные сбои повторяются один раз; запрос с отозванным ключом не повторяется никогда, ведь повтор в платном API превращает одну ошибку в три.

Сгенерированные методы ничего не запирают

// Released after this SDK version? Call it anyway.
await occult.call("/api/astro/some-new-endpoint/", { date_time });

Типизированные методы — обёртки над одним публичным вызовом, поэтому эндпоинт, вышедший после вашей версии пакета, доступен сразу, без ожидания нового релиза SDK.

Только на сервере

Ваш ключ тратит настоящие кредиты и никогда не должен попадать в браузерный бандл — там его прочитает любой, кто откроет devtools. API принимает вызовы из браузера, так что запрос с фронтенда сработает — и заодно отдаст ваш ключ каждому посетителю. Вызывайте SDK на бэкенде и передавайте на фронтенд готовый результат.

Что для чего