@asksoma/astro-client

Official TypeScript client + CLI for the AskSoma Partner (Astrology Brain) API. Zero dependencies (uses global fetch). Node 18+, Deno, Bun, browsers.

Private / admin-issued. Partner (brain) keys are issued by AskSoma — they are not self-serve. Core endpoints work with any valid sk_live_ key.

Install & build (internal)

cd packages/astro-client
npm install
npm run build     # emits dist/

SDK usage

import { AskSomaClient } from '@asksoma/astro-client';

const soma = new AskSomaClient({ apiKey: process.env.ASKSOMA_API_KEY! });
// Default base: https://api.asksoma.ai

// Brain — muhurat (electional windows; needs scope 'brain')
const muhurat = await soma.muhurat({
  chart: { date: '1994-08-19', time: '06:15', lat: 19.07, lon: 72.87, tz: 5.5 },
  activity: 'wedding',
  from: '2026-08-01',
  to: '2026-09-30',
  event: { lat: 19.076, lon: 72.877, tz: 5.5 },
});

// Brain — daily frames (Rahu Kaal / Choghadiya / Amrit — not ranked windows)
const daily = await soma.muhuratDaily({
  date: '2026-07-24', lat: 28.6139, lon: 77.209, tz: 5.5,
  signature: 'daily_rahu_kaal',
});

// Brain — occasion catalog for Finder UIs
const catalog = await soma.muhuratCatalog();

// Brain — other
const dasha = await soma.dasha({ date: '1990-05-15', time: '14:30', lat: 28.6139, lon: 77.209, tz: 5.5 });
const timing = await soma.timing({
  chart: { date: '1994-08-19', time: '06:15', lat: 19.07, lon: 72.87, tz: 5.5 },
  domain: 'marriage',
});

// Core (any valid key)
await soma.natalChart({ date: '1990-05-15', time: '14:30', lat: 28.6139, lon: 77.209, tz: 5.5 });
await soma.chatCompletions({
  messages: [{ role: 'user', content: 'Explain the top muhurat window in plain English.' }],
});

tz is a numeric UTC offset in hours (e.g. 5.5 for IST) on brain routes. Errors throw AskSomaApiError with .status, .code, and .scope (e.g. scope_required).

Agent / LLM auto-connect

Hand coding agents this URL first: https://asksoma.ai/partner-llm.txt
(machine map: https://asksoma.ai/partner-connect.json). Repo source: docs/PARTNER_API_LLM.md.

Muhurat vs timing

| Method | Meaning | |--------|---------| | muhurat() | When to do X — ranked electional windows (Good Timings) | | timing() | When will X happen — Phalita life-event bands |

Do not merge these.

CLI usage

export ASKSOMA_API_KEY=sk_live_...
npx asksoma muhurat --date 1994-08-19 --time 06:15 --lat 19.07 --lon 72.87 --tz 5.5 \
  --activity wedding --from 2026-08-01 --to 2026-09-30
npx asksoma catalog
npx asksoma daily --date 2026-07-24 --lat 28.6139 --lon 77.209 --tz 5.5
npx asksoma dasha --date 1990-05-15 --time 14:30 --lat 28.6139 --lon 77.209 --tz 5.5
npx asksoma help

Determinism

Every brain response carries meta.engine_version and is computed with pinned Lahiri ayanamsa + Placidus houses — same inputs → same output.

MCP (alternative)

AskSoma also exposes find_muhurat, get_dasha, get_transits, get_composite_chart at https://api.asksoma.ai/mcp — see docs/PARTNER_API_CONNECT.md.

Security

Never put sk_live_ keys in a browser. For embeds, proxy through your backend (see packages/muhurat-embed and docs/PARTNER_API_EMBED.md).