TypeScript & JavaScript SDK (@baziapi/sdk)

v1.0.0

Zero-dependency, 100% type-safe client for Node.js 18+, Bun, Deno, Edge Runtime, and modern browsers.

Official SDKs

The official @baziapi/sdk provides complete autocomplete for all BaZi chart entities (Four Pillars, Heavenly Stems, Earthly Branches, Ten Gods, Hidden Stems, Five Element Analysis, and Luck Pillars). Features automatic retries with exponential backoff and isomorphic Webhook verification.

Installation

Bash

npm install @baziapi/sdk

Quick Start

Quick Start Calculation

TypeScript

import { BaziClient } from '@baziapi/sdk';

const client = new BaziClient({ apiKey: process.env.BAZI_API_KEY! });

const chart = await client.bazi.calculate({
  birthDate: '1998-08-12',
  birthTime: '10:30',
  gender: 'male',
  timezone: 'Asia/Dhaka',
  language: 'en',
});

console.log('Year Pillar :', chart.pillars.year);
console.log('Month Pillar:', chart.pillars.month);
console.log('Day Pillar  :', chart.pillars.day, '(Day Master:', chart.heavenlyStems.dayStem + ')');
console.log('Hour Pillar :', chart.pillars.hour);
console.log('Strongest Element:', chart.analysis.strongestElement);

API Parameters

Parameter	Type	Required	Default	Description
`birthDate`	`string`	Required	—	Birth date in YYYY-MM-DD format (e.g. 1998-08-12).
`birthTime`	`string`	Required	—	Birth time in 24-hour HH:mm format (e.g. 10:30).
`gender`	`'male' \| 'female'`	Required	—	Gender for Luck Pillar direction calculation.
`timezone`	`string`	Optional	`Asia/Shanghai`	IANA Timezone string (e.g. Asia/Dhaka).
`language`	`'en' \| 'zh'`	Optional	`en`	Output language for names and terms.

More Examples

Isomorphic Webhook Verification

TypeScript

import { verifyWebhookSignature } from '@baziapi/sdk';

const isValid = await verifyWebhookSignature({
  payload: rawBodyBufferOrString,
  signature: req.headers['x-bazi-signature'],
  secret: process.env.BAZI_WEBHOOK_SECRET!,
});

Error Handling

TypeScript

import { BaziError, ApiError, ValidationError, TimeoutError } from '@baziapi/sdk';

try {
  const chart = await client.bazi.calculate({ birthDate: '1998-08-12', birthTime: '10:30', gender: 'male' });
} catch (err) {
  if (err instanceof ValidationError) console.error('Invalid client input:', err.message);
  else if (err instanceof ApiError) console.error('API Error HTTP', err.statusCode, err.requestId);
  else if (err instanceof TimeoutError) console.error('Request timed out.');
}

HTTP Status & Error Codes

Python SDK (PyPI)

Something unclear? Contact developer support.