TypeScript SDK

@navapatra/sdk is a small TypeScript client generated from the same OpenAPI spec as the API reference. It has no runtime dependencies, ships ESM and CommonJS with type declarations, and runs on Node 18+, Deno, Bun, Cloudflare Workers, browsers and React Native.

Install

npm install @navapatra/sdk

The package is published to npm with the first public release. For other languages, the Python, PHP and HTTP examples in every guide work as they are, or generate a client from the OpenAPI spec behind the API reference.

First call

import { Navapatra } from '@navapatra/sdk';

const client = new Navapatra({ apiKey: process.env.NAVAPATRA_API_KEY! });

const kundali = await client.kundali.create({
  birth: { calendar: 'BS', date: '2050-05-12', time: '14:35', place: { lat: 28.2096, lng: 83.9856 } },
  include: ['svg'],
  lang: 'ne',
});

console.log(kundali.lagna.sign.name, kundali.moon.nakshatra.name);

To try it without signing up, pass apiKey: 'demo'; it accepts the five sample subjects returned by client.meta.get().

Options

new Navapatra({
  apiKey: 'sk_live_...',     // required: a key or a client token
  baseUrl: 'https://api.navapatra.com',     // API origin without /v1 (this is the default)
  version: '2026-11-01',  // sent as Navapatra-Version; default: your key's pinned version
  fetch: customFetch,        // default: the global fetch
  timeoutMs: 30_000,         // per attempt
  maxRetries: 2,             // on 408, 429, 5xx, timeouts and network errors
});

Every method also accepts a last argument { signal, timeoutMs, maxRetries, version }. Retries back off and honour Retry-After.

Methods

Method	Endpoint	Credits
`kundali.create(body)`	`POST /v1/kundali`	1
`kundali.planets(body)`	`POST /v1/kundali/planets`	1
`dasha.create(body)`	`POST /v1/dasha`	1
`matching.ashtakoota(body)`	`POST /v1/matching/ashtakoota`	1
`matching.batch(body)`	`POST /v1/matching/ashtakoota/batch`	1 per pair
`matching.rashi(body)`	`POST /v1/matching/rashi`	1
`panchang.day(query)`	`GET /v1/panchang/day`	1
`panchang.range(query)`	`GET /v1/panchang/range`	1 per started 31 days
`calendar.convert(query)`	`GET /v1/calendar/convert`	1
`calendar.month(query)`	`GET /v1/calendar/month`	1
`charts.svg(body)`	`POST /v1/charts/svg` (JSON `{ svg }`)	1
`places.search(query)`	`GET /v1/places/search`	0
`timezone.get(query)`	`GET /v1/timezone`	1
`tokens.create(body)`	`POST /v1/tokens` (`sk_live_` only)	0
`usage.get()`	`GET /v1/usage`	0
`meta.get()`	`GET /v1/meta`	0

Credits, rate limits and request ids

Awaiting a method gives you the parsed body. Call .withResponse() to get the metering headers too:

const { data, meta } = await client.panchang
  .day({ date: '2083-01-01', calendar: 'BS', lat: 27.7172, lng: 85.324 })
  .withResponse();

meta.creditsCharged;   // 1
meta.creditsRemaining; // your organization's balance
meta.requestId;        // quote this to support
meta.rateLimit;        // { limit, remaining, reset } or null

Errors

Every failure is a NavapatraError. API errors carry the problem document:

import { NavapatraError } from '@navapatra/sdk';

try {
  await client.kundali.create({ birth });
} catch (err) {
  if (err instanceof NavapatraError) {
    err.status;    // 422
    err.code;      // 'ambiguous_place'
    err.requestId; // for support
    err.problem;   // { title, detail, candidates, errors, topUpUrl, ... }
  }
}

Failures before any response arrives have status: 0 and one of the codes connection_error, timeout, aborted, invalid_response, missing_api_key or secret_key_in_browser.

Browsers and apps

The client refuses to start with a secret key (sk_live_, sk_test_) when a window global exists, which covers browsers and React Native. In client code use a publishable key restricted to your origins, or a client token from your backend:

// On your server, with sk_live_
const { token } = await server.tokens.create({ scopes: ['kundali', 'charts.svg'], ttlSeconds: 600 });

// In the app
const client = new Navapatra({ apiKey: token });

The full pattern, with React Native and Flutter code, is in Mobile apps and the backend proxy.