asktian-sdk

Official JavaScript/TypeScript SDK for the askTIAN Metaphysics API — 37 divination traditions, 49 endpoints including Qimen Dunjia, Jyotish, Ifá, Mahabote, 十二宮 Twelve Palaces, Tarot, Runes, Numerology, and TIAN Blended synthesis endpoints.

Installation

npm install asktian-sdk
# or
pnpm add asktian-sdk
# or
yarn add asktian-sdk

Quick Start

import { AskTianClient } from "asktian-sdk";

const client = new AskTianClient({ apiKey: "at_live_your_key_here" });

// Qimen Dunjia
const reading = await client.qimen.calculate({
  date: "2026-03-19",
  time: "10:00",
  question: "Should I sign the contract today?",
});

// Mahabote (Burmese Astrology) — new in v1.5.0
const mahabote = await client.mahabote.calculate({
  birthDate: "1990-01-15",
  question: "What does my birth planet reveal about my career?",
});
// Wednesday PM births → Rahu planet
const rahuReading = await client.mahabote.calculate({
  birthDate: "1990-03-14",
  isPM: true,
  question: "What challenges should I prepare for?",
});

// 十二宮 Twelve Palaces (Guiguzi Palace Destiny) — new in v1.6.0
const twelvePalaces = await client.twelvepalaces.calculate({
  birthYear: 1990,
  birthMonth: 3,
  birthDay: 15,
  birthHour: 10,
  question: "What does my palace destiny reveal about my fortune?",
});
// twelvePalaces.palace        → 9
// twelvePalaces.degree        → 0
// twelvePalaces.fortuneTitle  → "智慧之命"
// twelvePalaces.poem          → classical 4-line verse
// twelvePalaces.marriage      → marriage reading
// twelvePalaces.wealth        → wealth reading

// TIAN Global — cross-civilisational synthesis across all 5 traditions
const global = await client.tian.global({
  birthdate: "1990-01-15",
  birthTime: "06:30",
  birthPlace: "Singapore",
  question: "Should I launch my business this quarter?",
});
// v1.8.0: signProfile and compatProfile returned directly
// global.signProfile?.mantra          → "I Use"
// global.signProfile?.majorArcana     → "The Devil"
// global.compatProfile?.loveDimensionLabel → "Positive"

Quick Reference — New Interfaces (v1.7.0+)

| Interface | Endpoint | Field | Since | |-----------|----------|-------|-------| | ChineseZodiacProfile | almanac.zodiacSign | chineseProfile | v1.7.0 | | HoroscopeSignProfile | almanac.zodiacSign | westernProfile | v1.7.0 | | HoroscopeSignProfile | horoscope.calculate | signProfile | v1.7.0 | | CompatDimension | (used inside ZodiacDimensions / HoroscopeDimensions) | — | v1.7.0 | | ZodiacDimensions | compatibility.zodiac | dimensions | v1.7.0 | | ZodiacDimensions | compatibility.birthday | dimensions | v1.7.0 | | HoroscopeDimensions | compatibility.birthday | horoscopeDimensions | v1.7.0 | | TianGlobalSignProfile | tian.global | signProfile | v1.8.0 | | TianGlobalCompatProfile | tian.global | compatProfile | v1.8.0 | | TianGlobalDoneEvent | tian.global stream | done event (extended) | v1.9.0 | | TianGlobalStreamChunk | tian.global stream | full event union | v1.9.0 | | ZodiacCompatResponse | compatibility.zodiac | full response | v2.0.0 | | BirthdayCompatResponse | compatibility.birthday | full response | v2.0.0 | | AlmanacZodiacResponse | almanac.zodiacSign | full response | v2.0.0 | | HoroscopeResponse | horoscope.calculate | full response | v2.0.0 | | DivinationHolyMeaning | divination.draw | holyMeaning oracle map | v2.1.0 | | DivinationDrawResponse | divination.draw | full response | v2.1.0 | | AlmanacDailyResponse | almanac.daily | full response with 黃曆 fields | v2.2.0 |

Rich Profiles & 4D Compatibility (v1.7.0+)

Since v1.7.0, several endpoints return enriched profile data sourced from the YouApp dataset.

import type {
  ChineseZodiacProfile,
  HoroscopeSignProfile,
  CompatDimension,
  ZodiacDimensions,
  HoroscopeDimensions,
  TianGlobalSignProfile,
  TianGlobalCompatProfile,
} from "asktian-sdk";

// almanac.zodiacSign — 60-element Chinese zodiac profile + Western sign profile
const zodiac = await client.almanac.zodiacSign({ birthDate: "1990-01-15" });
const chinese: ChineseZodiacProfile | null = zodiac.chineseProfile;
// chinese?.personality, chinese?.strengths, chinese?.career, chinese?.love
const western: HoroscopeSignProfile | null = zodiac.westernProfile;
// western?.mantra, western?.majorArcana, western?.medical, western?.herbalAllies

// compatibility.zodiac — 5-dimension Chinese zodiac compatibility
const compat = await client.compatibility.zodiac({ animal1: "rat", animal2: "dragon" });
const dims: ZodiacDimensions | null = compat.dimensions;
// dims?.love.label   → "Positive"
// dims?.love.text    → full description
// dims?.career, dims?.wealth, dims?.health, dims?.marriage

// horoscope.calculate — Western sign profile on the sun sign
const horoscope = await client.horoscope.calculate({ birthdate: "1990-01-15" });
const profile: HoroscopeSignProfile | null = horoscope.signProfile;
// profile?.mantra, profile?.majorArcana, profile?.bodyParts, profile?.symbolism

// tian.global — signProfile and compatProfile at the top level (v1.8.0+)
const g = await client.tian.global({ birthdate: "1990-01-15", ... });
const sp: TianGlobalSignProfile | null = g.signProfile;
// sp?.westernSign → "capricorn", sp?.mantra → "I Use", sp?.majorArcana → "The Devil"
const cp: TianGlobalCompatProfile | null = g.compatProfile;
// cp?.chineseAnimal → "rat", cp?.partnerAnimal → "dragon", cp?.loveDimensionLabel → "Positive"

Streaming — tian.global (v1.9.0+)

Use TianGlobalStreamChunk for a fully typed for await loop over the tian.global stream. The stream yields four event types: system (per-tradition result), synthesis_chunk (LLM token), done (final result with signProfile + compatProfile), and error.

import { AskTianClient } from "asktian-sdk";
import type { TianGlobalStreamChunk } from "asktian-sdk";

const client = new AskTianClient({ apiKey: process.env.ASKTIAN_API_KEY! });

let synthesis = "";

for await (const event of client.tian.global.stream({
  birthdate:  "1990-01-15",
  birthTime:  "06:30",
  birthPlace: "Singapore",
  question:   "Should I launch my business this quarter?",
}) as AsyncGenerator<TianGlobalStreamChunk>) {

  if (event.type === "system") {
    // Each tradition result arrives progressively
    console.log(`[${event.name}] score: ${event.score}`);
  }

  if (event.type === "synthesis_chunk") {
    process.stdout.write(event.chunk);
    synthesis += event.chunk;
  }

  if (event.type === "done") {
    console.log("\nBlended score:",  event.blendedScore);
    console.log("Mantra:",           event.signProfile?.mantra);
    console.log("Tarot archetype:",  event.signProfile?.majorArcana);
    console.log("Love label:",       event.compatProfile?.loveDimensionLabel);
  }
}

Type cast note: client.tian.global.stream() returns AsyncGenerator<TianStreamEvent> at the base type level. Cast to AsyncGenerator<TianGlobalStreamChunk> to access the typed signProfile and compatProfile fields on the done event.

Available Systems

Eastern Tradition

| Method | System | |--------|--------| | client.qimen.calculate(input) | Qimen Dunjia 奇門遁甲 | | client.liuyao.calculate(input) | Liu Yao 六爻 | | client.meihua.calculate(input) | Meihua Yishu 梅花易數 | | client.daliu.calculate(input) | Da Liu Ren 大六壬 | | client.xiaoliu.calculate(input) | Xiao Liu Ren 小六壬 | | client.taiyi.calculate(input) | Tai Yi Shen Shu 太乙神數 | | client.nameAnalysis.analyze(input) | Chinese Name Analysis 姓名學 | | client.compatibility.calculate(input) | BaZi Compatibility 八字合婚 | | client.auspicious.analyze(input) | Auspicious Numbers 吉祥數字 | | client.almanac.get(input) | Chinese Almanac 通書 | | client.divination.draw(input) | Divination Lots 求籤 | | client.astrology.calculate(input) | Chinese Astrology 紫微斗數 | | client.mahabote.calculate(input) | Mahabote မဟာဘုတ် (Burmese Astrology) | | client.twelvepalaces.calculate(input) | 十二宮 Twelve Palaces 鬼谷子命宮 |

Western Tradition

| Method | System | |--------|--------| | client.tarot.draw(input) | Tarot | | client.coinFlip.flip(input) | Coin Flip Oracle | | client.runes.cast(input) | Norse Runes | | client.numerology.calculate(input) | Numerology | | client.zodiac.calculate(input) | Western Zodiac Compatibility | | client.birthday.compare(input) | Birthday Compatibility | | client.bloodtype.compare(input) | Blood Type Compatibility |

Indian Tradition

| Method | System | |--------|--------| | client.jyotish.calculate(input) | Jyotish (Vedic Astrology) | | client.anka.calculate(input) | Anka Shastra (Indian Numerology) |

African Tradition

| Method | System | |--------|--------| | client.ifa.calculate(input) | Ifá Divination | | client.vodun.calculate(input) | Vodun Oracle | | client.hakata.calculate(input) | Hakata (Bone Throwing) |

Islamic Tradition

| Method | System | |--------|--------| | client.rammal.calculate(input) | Ilm al-Raml (Geomancy) | | client.khatt.calculate(input) | Khatt al-Raml |

TIAN Blended Synthesis

| Method | Traditions Combined | |--------|---------------------| | client.tian.eastern(input) | All Eastern systems | | client.tian.western(input) | All Western systems | | client.tian.eastwest(input) | Eastern + Western | | client.tian.african(input) | All African systems | | client.tian.islamic(input) | All Islamic systems | | client.tian.indian(input) | All Indian systems | | client.tian.global(input) | All 5 traditions — full synthesis (29 systems) |

Error Handling

import { AskTianClient, AskTianError } from "asktian-sdk";

const client = new AskTianClient({ apiKey: "at_live_your_key_here" });

try {
  const result = await client.qimen.calculate({
    date: "2026-03-19",
    time: "10:00",
    question: "Should I proceed?",
  });
  console.log(result);
} catch (err) {
  if (err instanceof AskTianError) {
    console.error(`API error ${err.status}: ${err.message}`);
    // err.status: HTTP status code (401, 403, 429, etc.)
    // err.body: full error response body
  }
}

Changelog

v2.2.0 (2026-04-22)

• Breaking change: none — fully backwards-compatible with v2.1.x
• Added AlmanacDailyResponse interface — types the full almanac.daily response with complete 黃曆 fields
  • Core fields: date, lunarDate, lunarYear, lunarMonth, lunarDay, yearGanZhi, monthGanZhi, dayGanZhi, heavenlyStem, earthlyBranch, yearZodiac, dayZodiac
  • 十二建除: twelveValue, twelveDeity, twelveDeityLuck, isHuangDao, naYin
  • Activities: auspiciousActivities, inauspiciousActivities
  • New in v2.2.0: jiShen (吉神), xiongSha (凶煞), pengZuGan, pengZuZhi, taiShen, xiu, xiuLuck, xiuSong, liuYao, nineStar
  • Direction fields: positionCai, positionXi, positionFu, positionYangGui, positionYinGui
  • overallFortune, score
• client.almanac.daily() now returns Promise<AlmanacDailyResponse> instead of Promise<unknown>
• client.almanac.zodiacSign() now returns Promise<AlmanacZodiacResponse> instead of Promise<unknown>
• Almanac DB extended to 2050-12-31 (25-year horizon, all dates served from fast DB path)
• Updated Quick Reference table with v2.2.0 entry

v2.1.0 (2026-04-19)

• Breaking change: none — fully backwards-compatible with v2.0.x
• Added DivinationHolyMeaning interface — typed map of life-domain oracle categories (聖意)
  • Keys: 求財, 交易, 婚姻, 六甲, 自身, 疾病, 家運, 尋人, 失物, 移徙 (plus index signature for other systems)
• Added DivinationDrawResponse interface — types the full divination.draw response
  • lotNumber, title?, fortuneLevel?, poemText?, interpretation?, dongpoJie?, bixianZhu?, story?, holyMeaning?: DivinationHolyMeaning, score, creditsUsed?, system?
• client.divination.draw() now returns Promise<DivinationDrawResponse> instead of Promise<unknown>
• holyMeaning is currently populated for the wenshu system (100 lots); additional temple systems will be backfilled in future releases
• Updated Quick Reference table with v2.1.0 entries

v2.0.0 (2026-04-08)

• Breaking change: none — fully backwards-compatible with v1.x
• Added ZodiacCompatResponse interface — types the full compatibility.zodiac response
  • score, level, description, dimensions?: ZodiacDimensions
• Added BirthdayCompatResponse interface — types the full compatibility.birthday response
  • score, romanceScore, friendshipScore, marriageScore, dimensions?, horoscopeDimensions?
• Added AlmanacZodiacResponse interface — types the full almanac.zodiacSign response
  • western?, chinese?, chineseProfile?: ChineseZodiacProfile, westernProfile?: HoroscopeSignProfile
• Added HoroscopeResponse interface — types the full horoscope.calculate response
  • sunSign, moonSign?, ascendant?, elementProfile?, placements?, synthesis?, signProfile?: HoroscopeSignProfile, creditsUsed?
• Updated Quick Reference table with v2.0.0 entries
• Updated package description to reflect 37 traditions, 49 endpoints

v1.9.1 (2026-04-08)

• Added dedicated Streaming section to README with full TianGlobalStreamChunk usage example

v1.9.0 (2026-04-08)

• Added TianGlobalDoneEvent interface — extends TianDoneEvent with signProfile? and compatProfile?
• Added TianGlobalStreamChunk union type — typed for await loop for tian.global stream
• Updated Quick Reference table with v1.9.0 entries

v1.8.0 (2026-04-08)

• Added TianGlobalSignProfile interface — types signProfile returned by tian.global
  • westernSign: Western zodiac sign key (e.g. "capricorn")
  • mantra: Sign mantra (e.g. "I Use")
  • majorArcana: Major Arcana Tarot archetype (e.g. "The Devil")
• Added TianGlobalCompatProfile interface — types compatProfile returned by tian.global
  • chineseAnimal: Subject's Chinese zodiac animal
  • partnerAnimal: Partner's Chinese zodiac animal
  • loveDimensionLabel: Love dimension label from YouApp 4D data (e.g. "Positive")

v1.7.0 (2026-04-07)

• Added ChineseZodiacProfile interface — types chineseProfile on almanac.zodiacSign
  • 60-element profile (12 animals × 5 elements): general, personality, strengths, weakness, career, love, compatibility
• Added HoroscopeSignProfile interface — types westernProfile on almanac.zodiacSign and signProfile on horoscope.calculate
  • medical, bodyParts, herbalAllies, symbolism, houseRulership, mantra, majorArcana, minorArcana, famousPeople
• Added CompatDimension interface — single dimension with label and text
• Added ZodiacDimensions interface — types dimensions on compatibility.zodiac and compatibility.birthday
  • marriage, love, career, wealth, health — each a CompatDimension
• Added HoroscopeDimensions interface — types horoscopeDimensions on compatibility.birthday
  • intro, love, career, wealth, health

v1.6.0 (2026-04-06)

• Added client.twelvepalaces.calculate() — 十二宮 Twelve Palaces (鬼谷子命宮)
  • Zodiac year × birth month × birth day × birth hour → palace (4–14) + degree (0/2/4/6/8)
  • 61 palace-degree combinations with classical fortune titles (顯揚之命, 達貴之命, etc.)
  • Full classical readings: 4-line poem, marriage reading, wealth reading
  • comingSoon flag for palace 14 degree entries not in the classical source
• Updated tian.global to include 十二宮 (29 systems, 145 TIAN Points)
• Updated description: 37 traditions, 49 endpoints

v1.5.0 (2026-04-02)

• Added client.mahabote.calculate() — Mahabote မဟာဘုတ် (Burmese Astrology)
  • Birth planet derivation (7 planets + Rahu for Wednesday PM births)
  • 7-house natal chart and year chart
  • 108-year major/minor period cycle
  • Grand Trine & Minor Trine quality analysis
  • Planetary relationships (friends/enemies/elements)
  • Full synthesis paragraph
  • planetIcons field: CDN URLs for all 8 birth planet icons (default + shiny variants)
• Updated tian.global to include Mahabote (28 systems, 140 TIAN Points)
• Updated description: 36 traditions, 48 endpoints

v1.4.0

• Added client.life.boneWeight() — Chinese Bone Weight (骨重) life destiny system
• Added client.horoscope.calculate() — Western Horoscope (Sun/Moon/Rising + full planetary positions)
• Updated tian.global to 26 systems

v1.3.0

• Added client.ifa.calculate(), client.vodun.calculate(), client.hakata.calculate() — African tradition
• Added client.rammal.calculate(), client.khatt.calculate() — Islamic tradition
• Added client.tian.african(), client.tian.islamic() TIAN blended endpoints

v1.2.0

• Added client.jyotish.calculate(), client.anka.calculate() — Indian tradition
• Added client.tian.indian() TIAN blended endpoint

v1.1.0

• Added async-iterator stream() for all 7 TIAN blended endpoints

v1.0.0

• Initial release: Eastern + Western traditions, TIAN blended synthesis

Get an API Key

Visit asktian.com → Dashboard → API Keys. Pay with $TIAN on Base network to activate a subscription plan.

License

MIT