npm package: @solarita-sdk/typescript
Description: A TypeScript SDK for calculating Chinese astrology (Kanshi) and zodiac signs with high-precision astronomical calculations using astronomy-engine (Node.js) and pure JavaScript fallback (mobile/web)
Author: Oisu LLC
Latest version: 0.0.8

# solarita-sdk

A TypeScript SDK for calculating Chinese and Western astrology with high-precision calculations.

## Installation

```bash
npm install solarita-sdk
```

## Usage

### Basic Usage

```typescript
import { getKanshi, getZodiac, getSolaritaType } from 'solarita-sdk';

// Create a Date object with birth date and time
const birthday = new Date('1990-05-15T14:30:00');

// Get Kanshi (Chinese astrology) information
const kanshi = getKanshi(birthday);
console.log(kanshi);
// Output:
// {
//   yearStemType: "Steel",
//   yearStemChar: "庚",
//   yearStemCode: "6",
//   yearAnimal: "Horse",
//   yearAnimalChar: "午",
//   yearAnimalCode: "a07",
//   // ... more properties
// }

// Get Western astrology information
const zodiac = getZodiac(birthday);
console.log(zodiac);
// Output:
// {
//   sunSign: "Taurus",
//   sunCode: "b",
//   moonSign: "Gemini",
//   moonCode: "c",
//   mercurySign: "Taurus",
//   mercuryCode: "b",
//   // ... more properties
// }

// Get Solarita type (combination of zodiac and day stem)
const solaritaType = getSolaritaType(birthday);
console.log(solaritaType);
// Output: "b6" (example)
```

### API Reference

#### `getKanshi(birthday: Date): Kanshi`

Calculates the Chinese astrology (Kanshi) information for a given birth date and time.

**Parameters:**
- `birthday`: Date object containing birth date and time

**Returns:**
- `Kanshi` object containing:
  - `yearStemType`, `yearStemChar`, `yearStemCode`: Year stem information
  - `yearAnimal`, `yearAnimalChar`, `yearAnimalCode`: Year animal information
  - `monthStemType`, `monthStemChar`, `monthStemCode`: Month stem information
  - `monthAnimal`, `monthAnimalChar`, `monthAnimalCode`: Month animal information
  - `dayStemType`, `dayStemChar`, `dayStemCode`: Day stem information
  - `dayAnimal`, `dayAnimalChar`, `dayAnimalCode`: Day animal information
  - `hourStemType`, `hourStemChar`, `hourStemCode`: Hour stem information
  - `hourAnimal`, `hourAnimalChar`, `hourAnimalCode`: Hour animal information
  - `color`: RGB color string corresponding to `dayStemType`

#### `getZodiac(birthday: Date, latitude?: number, longitude?: number): ZodiacInfo`

Calculates the Western astrology information for a given birth date and location.

**Parameters:**
- `birthday`: Date object containing birth date and time
- `latitude`: Latitude of birth location (default: 35.6762 - Tokyo)
- `longitude`: Longitude of birth location (default: 139.6503 - Tokyo)

**Returns:**
- `ZodiacInfo` object containing:
  - `sunSign`, `sunCode`: Sun sign information
  - `moonSign`, `moonCode`: Moon sign information
  - `mercurySign`, `mercuryCode`: Mercury sign information
  - `venusSign`, `venusCode`: Venus sign information
  - `marsSign`, `marsCode`: Mars sign information
  - `jupiterSign`, `jupiterCode`: Jupiter sign information
  - `saturnSign`, `saturnCode`: Saturn sign information
  - `uranusSign`, `uranusCode`: Uranus sign information
  - `neptuneSign`, `neptuneCode`: Neptune sign information
  - `plutoSign`, `plutoCode`: Pluto sign information
  - `ascendant`, `ascendantCode`: Ascendant (rising sign) information
  - `MC`, `MCCode`: Midheaven (MC) information
  - `northNode`, `northNodeCode`: North Node information

#### `getSolaritaType(birthday: Date): string`

Calculates the Solarita type (combination of zodiac sign and day stem).

**Parameters:**
- `birthday`: Date object containing birth date and time

**Returns:**
- String representing the Solarita type (e.g., "b6")

## Types

### Kanshi

```typescript
type Kanshi = {
  hourStemType: string;
  hourStemChar: string;
  hourStemCode: string;
  dayStemType: string;
  dayStemChar: string;
  dayStemCode: string;
  monthStemType: string;
  monthStemChar: string;
  monthStemCode: string;
  yearStemType: string;
  yearStemChar: string;
  yearStemCode: string;
  hourAnimal: string;
  hourAnimalChar: string;
  hourAnimalCode: string;
  dayAnimal: string;
  dayAnimalChar: string;
  dayAnimalCode: string;
  monthAnimal: string;
  monthAnimalChar: string;
  monthAnimalCode: string;
  yearAnimal: string;
  yearAnimalChar: string;
  yearAnimalCode: string;
  /** RGB color corresponding to dayStemType */
  color: string;
};
```

### ZodiacInfo

```typescript
type ZodiacInfo = {
  sunSign: string;
  sunCode: string;
  moonSign: string;
  moonCode: string;
  mercurySign: string;
  mercuryCode: string;
  venusSign: string;
  venusCode: string;
  marsSign: string;
  marsCode: string;
  jupiterSign: string;
  jupiterCode: string;
  saturnSign: string;
  saturnCode: string;
  uranusSign: string;
  uranusCode: string;
  neptuneSign: string;
  neptuneCode: string;
  plutoSign: string;
  plutoCode: string;
  ascendant: string;
  ascendantCode: string;
  MC: string;
  MCCode: string;
  northNode: string;
  northNodeCode: string;
};
```

## Features

- High Precision: Uses astronomy-engine for accurate astronomical calculations
- Chinese Astrology: Complete Kanshi (Four Pillars) calculations
- Western Astrology: All major planets and points including Ascendant, MC, and North Node
- TypeScript Support: Full type definitions included
- Location Support: Customizable latitude/longitude for accurate house calculations
- Performance: Optimized calculations for both Node.js and mobile/web environments

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Type Checking

```bash
npm run typecheck
```

### Publishing

> **Important**: Supabase Functions import this SDK via npm. After making changes to the SDK, you must publish a new version to npm to ensure the functions use the updated code.

```bash
# Update version in package.json
npm version patch  # or minor/major

# Build and publish
npm run build
npm publish
```

## License

MIT