TypeScript & JavaScript SDK (@baziapi/sdk)

v2.0.2

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

Official SDKs

The official @baziapi/sdk (v2.0.2) provides complete autocomplete for all BaZi calculations, canonical v2 grouped taxonomy, programmatic Outbound Webhook management with your API Key, and cryptographically secure Webhook event verification with anti-replay attack protection.

Installation

$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.fourPillars.yearPillar);
console.log('Month Pillar:', chart.fourPillars.monthPillar);
console.log('Day Pillar  :', chart.fourPillars.dayPillar);
console.log('Hour Pillar :', chart.fourPillars.hourPillar);
console.log('Day Master  :', chart.traditionalMappings.relationshipMappings.dayRelationship);
console.log('Strongest Element:', chart.traditionalInterpretations.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' \| 'hi' \| 'bn' \| 'es'`	Optional	`en`	Output language localization for names, pillars, and terms ("en", "zh", "hi", "bn", "es").

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.