@baziapi/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,951 @@
+/**
+ * @file HttpClient.ts
+ * @description Native fetch-based HTTP client with timeout, retry, and error mapping.
+ * No external HTTP library dependencies — works in Node 18+, Bun, Deno, and browsers.
+ */
+/** Internal configuration for the HttpClient. */
+interface HttpClientConfig {
+    /** Root API URL without trailing slash. e.g. `https://api.bazi.com` */
+    readonly baseUrl: string;
+    /** API key for Bearer token authentication. */
+    readonly apiKey: string;
+    /** Request timeout in milliseconds. */
+    readonly timeout: number;
+    /** Maximum retry attempts for retryable failures. */
+    readonly retries: number;
+    /** Base delay in milliseconds for exponential backoff. */
+    readonly retryDelay: number;
+    /** Optional callback invoked on every SDK error. */
+    readonly onError?: ((error: Error) => void) | undefined;
+}
+/**
+ * Lightweight, native-fetch HTTP client.
+ * Handles authorization headers, timeouts, JSON parsing, error mapping, and retries.
+ */
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    /**
+     * Performs a GET request.
+     * @param path - URL path relative to baseUrl.
+     * @param bearerToken - Optional JWT bearer token.
+     */
+    get<T>(path: string, bearerToken?: string): Promise<T>;
+    /**
+     * Performs a POST request.
+     * @param path - URL path relative to baseUrl.
+     * @param body - JSON request body.
+     * @param bearerToken - Optional JWT bearer token.
+     */
+    post<T>(path: string, body?: unknown, bearerToken?: string): Promise<T>;
+    /**
+     * Performs a PATCH request.
+     * @param path - URL path relative to baseUrl.
+     * @param body - JSON request body.
+     * @param bearerToken - Optional JWT bearer token.
+     */
+    patch<T>(path: string, body?: unknown, bearerToken?: string): Promise<T>;
+    /**
+     * Performs a DELETE request.
+     * @param path - URL path relative to baseUrl.
+     * @param bearerToken - Optional JWT bearer token.
+     */
+    delete<T>(path: string, bearerToken?: string): Promise<T>;
+    private buildHeaders;
+    private buildUrl;
+    private executeRequest;
+    private request;
+}
+
+/**
+ * @file request.ts
+ * @description All SDK request DTOs. Mirrors backend Zod schemas exactly.
+ * All string fields use `Readonly` to prevent consumer mutation.
+ */
+/**
+ * Input required to calculate BaZi (Four Pillars of Destiny).
+ * Mirrors `baziValidationSchema` from the backend.
+ */
+interface BaziCalculateRequest {
+    /** Birth date in YYYY-MM-DD format. Required. */
+    readonly birthDate: string;
+    /** Birth time in HH:mm format. Optional — defaults to 12:00 on the backend. */
+    readonly birthTime?: string;
+    /** Biological gender. Required for luck pillar direction calculation. */
+    readonly gender: 'male' | 'female';
+    /**
+     * IANA timezone identifier.
+     * @default 'Asia/Shanghai'
+     * @example 'Asia/Dhaka', 'America/New_York', 'Europe/London'
+     */
+    readonly timezone?: string;
+    /**
+     * Response language.
+     * `'en'` returns English labels; `'zh'` returns Chinese characters.
+     * @default 'en'
+     */
+    readonly language?: 'en' | 'zh';
+}
+/**
+ * Request body for user registration.
+ * Mirrors `registerZodSchema` from the backend.
+ */
+interface RegisterRequest {
+    /** Display name. Required. */
+    readonly name: string;
+    /** Valid email address. Required. */
+    readonly email: string;
+    /** Password. Minimum 6 characters. Required. */
+    readonly password: string;
+    /** ISO 3166-1 alpha-2 country code or full name. Optional. */
+    readonly country?: string;
+}
+/**
+ * Request body for user login.
+ * Mirrors `loginZodSchema` from the backend.
+ */
+interface LoginRequest {
+    /** Registered email address. */
+    readonly email: string;
+    /** Account password. */
+    readonly password: string;
+}
+/**
+ * Request body for email verification via OTP.
+ * Mirrors `verifyEmailZodSchema` from the backend.
+ */
+interface VerifyEmailRequest {
+    /** Email address to verify. */
+    readonly email: string;
+    /** 6-character OTP received via email. */
+    readonly otp: string;
+}
+/**
+ * Request body for initiating a password reset.
+ * Mirrors `forgotPasswordZodSchema` from the backend.
+ */
+interface ForgotPasswordRequest {
+    /** Registered email address to send reset OTP. */
+    readonly email: string;
+}
+/**
+ * Request body for completing a password reset.
+ * Mirrors `resetPasswordZodSchema` from the backend.
+ */
+interface ResetPasswordRequest {
+    /** Email address associated with the account. */
+    readonly email: string;
+    /** 6-character OTP received via email. */
+    readonly otp: string;
+    /** New password. Minimum 6 characters. */
+    readonly newPassword: string;
+}
+/**
+ * Request body for changing password while authenticated.
+ * Mirrors `changePasswordZodSchema` from the backend.
+ */
+interface ChangePasswordRequest {
+    /** Current account password. */
+    readonly oldPassword: string;
+    /** New password. Minimum 6 characters. */
+    readonly newPassword: string;
+}
+
+/**
+ * @file response.ts
+ * @description All SDK response types. Mirrors backend bazi.interface.ts and auth.interface.ts exactly.
+ * Every nullable field on the backend is typed as `T | null` here.
+ */
+/** Standard API response envelope returned by every endpoint. */
+interface ApiResponse<T> {
+    success: boolean;
+    message: string | null;
+    data: T | null;
+}
+/** The original input echoed back in the response. */
+interface BaziInput {
+    birthDate: string;
+    birthTime: string;
+    gender: 'male' | 'female';
+    timezone: string;
+    language: string;
+}
+/** Solar (Gregorian) calendar information. */
+interface SolarInfo {
+    solarYear: number;
+    solarMonth: number;
+    solarDay: number;
+    solarHour: number;
+    solarMinute: number;
+    solarDateTime: string;
+    weekDay: string;
+}
+/** Lunar calendar information. */
+interface LunarInfo {
+    lunarYear: number;
+    lunarMonth: number;
+    lunarDay: number;
+    leapMonth: number;
+    chineseDate: string;
+}
+/** The Four Pillars (Year, Month, Day, Hour). */
+interface FourPillars {
+    yearPillar: string;
+    monthPillar: string;
+    dayPillar: string;
+    hourPillar: string;
+}
+/** Advanced pillars: TaiYuan, MingGong, ShenGong. */
+interface AdvancedPillars {
+    taiYuan: string;
+    mingGong: string;
+    shenGong: string;
+}
+/** Heavenly Stems for each pillar. */
+interface HeavenlyStems {
+    yearStem: string;
+    monthStem: string;
+    dayStem: string;
+    hourStem: string;
+}
+/** Earthly Branches for each pillar. */
+interface EarthlyBranches {
+    yearBranch: string;
+    monthBranch: string;
+    dayBranch: string;
+    hourBranch: string;
+}
+/** Five Elements (WuXing) mapping and statistics. */
+interface FiveElements {
+    yearElement: string;
+    monthElement: string;
+    dayElement: string;
+    hourElement: string;
+    /** Percentage breakdown: `{ Wood: '25%', Fire: '0%', ... }` */
+    statistics: Record<string, string>;
+}
+/** Hidden Stems inside each Earthly Branch. */
+interface HiddenStems {
+    yearHiddenStems: string[];
+    monthHiddenStems: string[];
+    dayHiddenStems: string[];
+    hourHiddenStems: string[];
+}
+/** Ten Gods (ShiShen) for each pillar. */
+interface TenGods {
+    yearTenGod: string;
+    monthTenGod: string;
+    dayTenGod: string;
+    hourTenGod: string;
+    /** Percentage distribution of each Ten God across the chart. */
+    distribution?: Record<string, string>;
+}
+/** NaYin (Sound Element) for each pillar. */
+interface NaYin {
+    yearNaYin: string;
+    monthNaYin: string;
+    dayNaYin: string;
+    hourNaYin: string;
+}
+/** Chinese Zodiac information. */
+interface Zodiac {
+    chineseZodiac: string;
+    animal: string;
+}
+/** Western astrological constellation. */
+interface Constellation {
+    westernConstellation: string;
+}
+/** Current, previous, and next solar terms (JieQi). */
+interface SolarTerms {
+    currentSolarTerm: string | null;
+    previousSolarTerm: string | null;
+    nextSolarTerm: string | null;
+}
+/** A single year within a Luck Pillar cycle. */
+interface LiuNian {
+    year: number;
+    age: number;
+    pillar: string;
+}
+/** A single 10-year Luck Pillar (DaYun). */
+interface LuckPillarItem {
+    age: number;
+    pillar: string;
+    annualLuck?: LiuNian[];
+}
+/** Full Luck Pillar data including minor luck and direction. */
+interface LuckPillars {
+    direction: string | null;
+    forward: boolean;
+    startingAge: number;
+    startingDate: string | null;
+    pillars: LuckPillarItem[];
+    minorLuck: LiuNian[];
+}
+/** Auspicious and inauspicious stars / shen sha. */
+interface GodsAndStars {
+    nobleman: string[] | null;
+    peachBlossom: string[] | null;
+    academicStar: string[] | null;
+    travelHorse: string[] | null;
+    generalStar: string[] | null;
+}
+/** Branch interaction patterns within the chart. */
+interface Interactions {
+    clashes: string[];
+    combinations: string[];
+    punishments: string[];
+    harms: string[];
+}
+/** Deep analytical data derived from the chart. */
+interface Analysis {
+    dayMasterStrength: string | null;
+    strongestElement: string | null;
+    weakestElement: string | null;
+    missingElements: string[];
+    balanced: boolean | null;
+    favorableElements: string[];
+    unfavorableElements: string[];
+    yongShen: string | null;
+    voidBranch: string | null;
+    twelveGrowthPhases: string[] | null;
+    godsAndStars: GodsAndStars | null;
+    interactions: Interactions | null;
+}
+/** High-level life predictions derived from the chart. */
+interface LifePredictions {
+    careerDirection: string | null;
+    wealthPotential: string | null;
+    healthFocus: string[];
+}
+/** Annual luck overlay for the current year. */
+interface CurrentAnnualLuck {
+    currentYear: number;
+    annualPillar: string;
+    overallFortune: string;
+    keyEvents: string[];
+}
+/**
+ * Complete BaZi calculation response.
+ * Mirrors `IBaziResponseData` from the backend exactly.
+ * Fields can be `null` for FREE-tier users after the trial period.
+ */
+interface BaziCalculateResponse {
+    input: BaziInput;
+    solar: SolarInfo | null;
+    lunar: LunarInfo | null;
+    pillars: FourPillars | null;
+    advancedPillars: AdvancedPillars | null;
+    heavenlyStems: HeavenlyStems | null;
+    earthlyBranches: EarthlyBranches | null;
+    fiveElements: FiveElements | null;
+    hiddenStems: HiddenStems | null;
+    tenGods: TenGods | null;
+    naYin: NaYin | null;
+    zodiac: Zodiac | null;
+    constellation: Constellation | null;
+    solarTerms: SolarTerms | null;
+    luckPillars: LuckPillars | null;
+    analysis: Analysis | null;
+    lifePredictions: LifePredictions | null;
+    currentAnnualLuck: CurrentAnnualLuck | null;
+}
+/** User object returned after authentication. */
+interface AuthUser {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+    isEmailVerified: boolean;
+}
+/** Response from login endpoint. */
+interface LoginResponse {
+    accessToken: string;
+    refreshToken: string;
+    user: AuthUser;
+}
+/** Response from refresh-token endpoint. */
+interface RefreshTokenResponse {
+    accessToken: string;
+}
+/** A single API key item. */
+interface ApiKeyItem {
+    id: string;
+    prefix: string;
+    name: string | null;
+    isActive: boolean;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+/** Response from generate API key endpoint. */
+interface GeneratedApiKey {
+    id: string;
+    prefix: string;
+    /** The full raw key — only returned once. Store it securely. */
+    key: string;
+    name: string | null;
+    isActive: boolean;
+    createdAt: string;
+}
+/** Response from list API keys endpoint. */
+type ApiKeyListResponse = ApiKeyItem[];
+/** Full user profile from /auth/me. */
+interface UserProfile {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+    country: string | null;
+    isEmailVerified: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * @file resources/bazi.ts
+ * @description BaZi calculation resource. Handles POST /api/v1/bazi/calculate.
+ */
+
+/**
+ * Resource class for BaZi (Four Pillars of Destiny) calculations.
+ * Access via `client.bazi`.
+ */
+declare class BaziResource {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Calculate BaZi (Four Pillars of Destiny) for a given birth date and time.
+     *
+     * Validates input client-side before sending the request.
+     * Requires an API key set on the client.
+     *
+     * @param input - The birth information required for calculation.
+     * @returns A promise resolving to the full BaZi analysis result.
+     *
+     * @throws {ValidationError} If the input fails client-side validation.
+     * @throws {ApiError} If the server rejects the request (4xx/5xx).
+     * @throws {TimeoutError} If the request exceeds the configured timeout.
+     * @throws {NetworkError} If a network-level failure occurs.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.bazi.calculate({
+     *   birthDate: '1998-08-12',
+     *   birthTime: '10:30',
+     *   gender: 'male',
+     *   timezone: 'Asia/Dhaka',
+     *   language: 'en',
+     * });
+     *
+     * console.log(result.pillars);
+     * console.log(result.luckPillars?.pillars);
+     * ```
+     */
+    calculate(input: BaziCalculateRequest): Promise<BaziCalculateResponse>;
+}
+
+/**
+ * @file resources/auth.ts
+ * @description Authentication resource. Handles all /api/v1/auth/* endpoints.
+ */
+
+/**
+ * Resource class for authentication operations.
+ * Access via `client.auth`.
+ *
+ * JWT tokens returned by `login()` must be stored by the consumer
+ * and passed back via `bearerToken` on protected calls.
+ */
+declare class AuthResource {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * Register a new user account.
+     *
+     * @param input - Registration data including name, email, and password.
+     * @returns A promise resolving to `null` on success (email verification required).
+     *
+     * @throws {ValidationError} If input is invalid.
+     * @throws {ApiError} If the email is already registered (409).
+     *
+     * @example
+     * ```typescript
+     * await client.auth.register({
+     *   name: 'Jane Doe',
+     *   email: 'jane@example.com',
+     *   password: 'secret123',
+     * });
+     * ```
+     */
+    register(input: RegisterRequest): Promise<null>;
+    /**
+     * Verify an email address using the OTP sent during registration.
+     *
+     * @param input - Email address and 6-digit OTP.
+     * @returns A promise resolving to `null` on success.
+     *
+     * @throws {ValidationError} If input is invalid.
+     * @throws {ApiError} If OTP is incorrect or expired (400).
+     */
+    verifyEmail(input: VerifyEmailRequest): Promise<null>;
+    /**
+     * Log in with email and password.
+     *
+     * @param input - Email and password credentials.
+     * @returns A promise resolving to access token, refresh token, and user data.
+     *
+     * @throws {ValidationError} If input is invalid.
+     * @throws {ApiError} If credentials are incorrect (401).
+     *
+     * @example
+     * ```typescript
+     * const { accessToken, user } = await client.auth.login({
+     *   email: 'jane@example.com',
+     *   password: 'secret123',
+     * });
+     * ```
+     */
+    login(input: LoginRequest): Promise<LoginResponse>;
+    /**
+     * Refresh an expired access token using a valid refresh token.
+     *
+     * @param refreshToken - A valid refresh token previously issued by `login()`.
+     * @returns A promise resolving to a new access token.
+     *
+     * @throws {ApiError} If the refresh token is invalid or expired (401).
+     */
+    refreshToken(refreshToken: string): Promise<RefreshTokenResponse>;
+    /**
+     * Initiate a password reset flow by requesting an OTP via email.
+     *
+     * @param input - Email address of the account to reset.
+     * @returns A promise resolving to `null` on success.
+     *
+     * @throws {ValidationError} If the email is invalid.
+     * @throws {ApiError} If the email is not registered (404).
+     */
+    forgotPassword(input: ForgotPasswordRequest): Promise<null>;
+    /**
+     * Complete a password reset using the OTP received via email.
+     *
+     * @param input - Email, OTP, and new password.
+     * @returns A promise resolving to `null` on success.
+     *
+     * @throws {ValidationError} If input is invalid.
+     * @throws {ApiError} If OTP is incorrect or expired (400).
+     */
+    resetPassword(input: ResetPasswordRequest): Promise<null>;
+    /**
+     * Change the authenticated user's password.
+     * Requires a valid JWT access token.
+     *
+     * @param input - Old password and new password.
+     * @param bearerToken - Valid JWT access token from `login()`.
+     * @returns A promise resolving to `null` on success.
+     *
+     * @throws {ValidationError} If input is invalid.
+     * @throws {ApiError} If old password is incorrect (401) or token is invalid.
+     */
+    changePassword(input: ChangePasswordRequest, bearerToken: string): Promise<null>;
+    /**
+     * Retrieve the authenticated user's profile.
+     * Requires a valid JWT access token.
+     *
+     * @param bearerToken - Valid JWT access token from `login()`.
+     * @returns A promise resolving to the user profile.
+     *
+     * @throws {ApiError} If the token is invalid or expired (401).
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.auth.me(accessToken);
+     * console.log(profile.email);
+     * ```
+     */
+    me(bearerToken: string): Promise<UserProfile>;
+    /**
+     * Log out the authenticated user, invalidating their session.
+     * Requires a valid JWT access token.
+     *
+     * @param bearerToken - Valid JWT access token from `login()`.
+     * @returns A promise resolving to `null` on success.
+     *
+     * @throws {ApiError} If the token is invalid or expired (401).
+     */
+    logout(bearerToken: string): Promise<null>;
+}
+
+/**
+ * @file resources/apiKey.ts
+ * @description API Key management resource. Handles all /api/v1/api-keys/* endpoints.
+ */
+
+/**
+ * Resource class for API Key management operations.
+ * Access via `client.apiKeys`.
+ *
+ * All methods require a valid JWT `bearerToken` from `client.auth.login()`.
+ */
+declare class ApiKeyResource {
+    private readonly http;
+    /** @internal */
+    constructor(http: HttpClient);
+    /**
+     * List all API keys associated with the authenticated user's account.
+     * Only the key prefix is returned — not the full raw key.
+     *
+     * @param bearerToken - Valid JWT access token from `client.auth.login()`.
+     * @returns A promise resolving to an array of API key metadata.
+     *
+     * @throws {ApiError} If the token is invalid or expired (401).
+     *
+     * @example
+     * ```typescript
+     * const keys = await client.apiKeys.list(accessToken);
+     * keys.forEach(key => console.log(key.prefix, key.isActive));
+     * ```
+     */
+    list(bearerToken: string): Promise<ApiKeyListResponse>;
+    /**
+     * Generate a new API key for the authenticated user.
+     *
+     * **Important:** The full raw key is returned only once in this response.
+     * Store it securely — it cannot be retrieved again.
+     *
+     * @param bearerToken - Valid JWT access token from `client.auth.login()`.
+     * @returns A promise resolving to the newly created API key including the full raw key.
+     *
+     * @throws {ApiError} If the token is invalid or the user's plan limit is reached.
+     *
+     * @example
+     * ```typescript
+     * const { key, prefix } = await client.apiKeys.create(accessToken);
+     * // Store `key` securely — it won't be shown again
+     * console.log('Your API key:', key);
+     * ```
+     */
+    create(bearerToken: string): Promise<GeneratedApiKey>;
+    /**
+     * Revoke (deactivate) an API key by its ID.
+     * Revoked keys are permanently disabled and cannot be re-activated.
+     *
+     * @param keyId - The ID of the API key to revoke.
+     * @param bearerToken - Valid JWT access token from `client.auth.login()`.
+     * @returns A promise resolving to the revoked API key metadata.
+     *
+     * @throws {ApiError} If the key is not found (404) or doesn't belong to the user (403).
+     *
+     * @example
+     * ```typescript
+     * await client.apiKeys.revoke(keyId, accessToken);
+     * ```
+     */
+    revoke(keyId: string, bearerToken: string): Promise<ApiKeyItem>;
+}
+
+/**
+ * @file BaziError.ts
+ * @description Base error class for all SDK errors.
+ * Every error thrown by the SDK extends this class.
+ */
+/**
+ * Discriminant union type for all SDK error kinds.
+ */
+type BaziErrorKind = 'api_error' | 'validation_error' | 'timeout_error' | 'network_error';
+/**
+ * Abstract base class for all BaZi SDK errors.
+ * Consumers can use `instanceof BaziError` to catch any SDK error.
+ */
+declare abstract class BaziError extends Error {
+    /** Machine-readable error kind for programmatic handling. */
+    abstract readonly kind: BaziErrorKind;
+    constructor(message: string);
+}
+
+/**
+ * @file constants.ts
+ * @description Shared SDK constants.
+ */
+/**
+ * The BaZi backend API version prefix.
+ * Used by resource classes to construct URL paths.
+ */
+declare const API_VERSION: "v1";
+
+/**
+ * @file WebhookService.ts
+ * @description Isomorphic HMAC-SHA256 Webhook signature verification.
+ * Works seamlessly across Node.js (18+), Bun, Deno, Cloudflare Workers, and Browser environments.
+ */
+interface VerifySignatureOptions {
+    /**
+     * Raw request body as a string or Uint8Array/Buffer.
+     */
+    payload: string | Uint8Array;
+    /**
+     * The signature header sent with the webhook (e.g. from `x-bazi-signature` or `x-webhook-signature`).
+     */
+    signature: string;
+    /**
+     * Your webhook endpoint signing secret (configured in the BaZi dashboard).
+     */
+    secret: string;
+    /**
+     * Optional tolerance in seconds to prevent replay attacks (if signature contains timestamp `t=...,v1=...`).
+     */
+    tolerance?: number;
+}
+/**
+ * Webhook signature verification service.
+ */
+declare class WebhookService {
+    /**
+     * Verifies an incoming webhook HMAC-SHA256 signature.
+     *
+     * @param options - Verification options including payload, signature, and secret.
+     * @returns `true` if the signature is valid; `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * import { BaziClient } from '@bazi/sdk';
+     *
+     * const client = new BaziClient();
+     * const isValid = await client.webhooks.verifySignature({
+     *   payload: rawBody,
+     *   signature: req.headers['x-bazi-signature'],
+     *   secret: process.env.BAZI_WEBHOOK_SECRET!,
+     * });
+     *
+     * if (!isValid) {
+     *   return res.status(401).send('Invalid signature');
+     * }
+     * ```
+     */
+    verifySignature(options: VerifySignatureOptions): Promise<boolean>;
+    /**
+     * Computes an HMAC-SHA256 digest in hex string format using Web Crypto API.
+     *
+     * @param payload - Raw request payload.
+     * @param secret - Secret key.
+     * @returns Hexadecimal digest string.
+     */
+    computeHmac(payload: string | Uint8Array, secret: string): Promise<string>;
+}
+/**
+ * Standalone helper function for verifying webhook signatures without instantiating `BaziClient`.
+ *
+ * @param options - Webhook verification options.
+ * @returns `true` if valid, `false` otherwise.
+ */
+declare function verifyWebhookSignature(options: VerifySignatureOptions): Promise<boolean>;
+
+/**
+ * @file client.ts
+ * @description BaziClient — the main entry point for the BaZi API SDK.
+ */
+
+/**
+ * Configuration options for `BaziClient`.
+ * All fields except `apiKey` are optional with safe defaults.
+ */
+interface BaziClientOptions {
+    /**
+     * Your BaZi API key (prefix: `bazi_`).
+     * Required for all BaZi calculation requests.
+     * Optional for auth-only use cases.
+     */
+    readonly apiKey?: string;
+    /**
+     * Base URL of the BaZi API server.
+     * @default 'https://api.bazi.dev'
+     */
+    readonly baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * Throws `TimeoutError` when exceeded.
+     * @default 10000
+     */
+    readonly timeout?: number;
+    /**
+     * Maximum number of retry attempts for transient failures (network errors, 5xx, 429).
+     * @default 3
+     */
+    readonly retries?: number;
+    /**
+     * Base delay in milliseconds between retry attempts (exponential backoff).
+     * Actual delay = `retryDelay * 2^attempt`.
+     * @default 500
+     */
+    readonly retryDelay?: number;
+    /**
+     * Optional callback invoked whenever the SDK throws an error.
+     * Useful for logging and monitoring integrations.
+     *
+     * @example
+     * ```typescript
+     * new BaziClient({
+     *   apiKey: 'bazi_xxx',
+     *   onError: (err) => Sentry.captureException(err),
+     * });
+     * ```
+     */
+    readonly onError?: (error: BaziError) => void;
+}
+
+declare class BaziClient {
+    private readonly httpClient;
+    /**
+     * BaZi calculation resource.
+     * Endpoint: `POST /api/v1/bazi/calculate`
+     */
+    readonly bazi: BaziResource;
+    /**
+     * Authentication resource.
+     * Endpoints: register, login, logout, verifyEmail, forgotPassword, resetPassword, changePassword, me
+     */
+    readonly auth: AuthResource;
+    /**
+     * API Key management resource.
+     * Endpoints: list, create, revoke
+     */
+    readonly apiKeys: ApiKeyResource;
+    /**
+     * Webhook utilities for verifying HMAC-SHA256 signatures.
+     */
+    readonly webhooks: WebhookService;
+    /**
+     * Creates a new BaziClient instance.
+     *
+     * @param options - Client configuration options.
+     *
+     * @example
+     * ```typescript
+     * // Production usage
+     * const client = new BaziClient({ apiKey: 'bazi_xxxx' });
+     *
+     * // Development / self-hosted
+     * const client = new BaziClient({
+     *   apiKey: 'bazi_xxxx',
+     *   baseUrl: 'http://localhost:5000',
+     *   timeout: 30_000,
+     *   retries: 1,
+     * });
+     * ```
+     */
+    constructor(options?: BaziClientOptions);
+    /**
+     * Direct convenience method to calculate BaZi (Four Pillars of Destiny).
+     * Shortcut for `client.bazi.calculate(input)`.
+     *
+     * @param input - The birth information required for calculation.
+     * @returns A promise resolving to the full BaZi analysis result.
+     */
+    calculate(input: BaziCalculateRequest): Promise<BaziCalculateResponse>;
+}
+
+/**
+ * @file ApiError.ts
+ * @description All SDK error subclasses: ApiError, ValidationError, TimeoutError, NetworkError.
+ */
+
+/**
+ * Thrown when the BaZi API returns a non-2xx HTTP response.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.bazi.calculate({ ... });
+ * } catch (error) {
+ *   if (error instanceof ApiError) {
+ *     console.error(error.statusCode, error.message);
+ *     console.error(error.errors); // server validation details
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends BaziError {
+    readonly kind: BaziErrorKind;
+    /** HTTP status code returned by the server. */
+    readonly statusCode: number;
+    /** Detailed server-side validation errors, if any. */
+    readonly errors: unknown[] | undefined;
+    /** Request ID from the `X-Request-ID` response header, if present. */
+    readonly requestId: string | undefined;
+    /**
+     * Raw `Retry-After` header value from the server response.
+     * Used internally by the retry layer — not intended for consumer use.
+     * @internal
+     */
+    readonly _retryAfter: string | null;
+    constructor(statusCode: number, message: string, errors?: unknown[], requestId?: string, retryAfter?: string | null);
+}
+/**
+ * Thrown when client-side input validation fails before a request is sent.
+ * The request is never made to the network in this case.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.bazi.calculate({ birthDate: 'bad-date', gender: 'male' });
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     console.error('Bad input:', error.message);
+ *     console.error('Field:', error.field);
+ *   }
+ * }
+ * ```
+ */
+declare class ValidationError extends BaziError {
+    readonly kind: BaziErrorKind;
+    /** The name of the field that failed validation. */
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Thrown when a request exceeds the configured `timeout` option.
+ *
+ * @example
+ * ```typescript
+ * const client = new BaziClient({ apiKey: '...', timeout: 5000 });
+ * try {
+ *   await client.bazi.calculate({ ... });
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     console.error('Request timed out after', error.timeoutMs, 'ms');
+ *   }
+ * }
+ * ```
+ */
+declare class TimeoutError extends BaziError {
+    readonly kind: BaziErrorKind;
+    /** The configured timeout in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Thrown when `fetch()` throws — typically caused by no internet connection,
+ * DNS resolution failures, or the server refusing the connection.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.bazi.calculate({ ... });
+ * } catch (error) {
+ *   if (error instanceof NetworkError) {
+ *     console.error('Network failure:', error.cause);
+ *   }
+ * }
+ * ```
+ */
+declare class NetworkError extends BaziError {
+    readonly kind: BaziErrorKind;
+    /** The original error thrown by `fetch()`. */
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+
+export { API_VERSION, ApiError, BaziClient, BaziError, NetworkError, TimeoutError, ValidationError, WebhookService, verifyWebhookSignature };
+export type { AdvancedPillars, Analysis, ApiKeyItem, ApiKeyListResponse, ApiResponse, AuthUser, BaziCalculateRequest, BaziCalculateResponse, BaziClientOptions, BaziErrorKind, BaziInput, ChangePasswordRequest, Constellation, CurrentAnnualLuck, EarthlyBranches, FiveElements, ForgotPasswordRequest, FourPillars, GeneratedApiKey, GodsAndStars, HeavenlyStems, HiddenStems, Interactions, LifePredictions, LiuNian, LoginRequest, LoginResponse, LuckPillarItem, LuckPillars, LunarInfo, NaYin, RefreshTokenResponse, RegisterRequest, ResetPasswordRequest, SolarInfo, SolarTerms, TenGods, UserProfile, VerifyEmailRequest, VerifySignatureOptions, Zodiac };