# apiworks-astro-node-sdk

**Repository Path**: wingerd/apiworks-astro-node-sdk

## Basic Information

- **Project Name**: apiworks-astro-node-sdk
- **Description**: Node.js SDK for ApiWorks 星盘 API（[astro.apiworks.com](https://astro.apiworks.com)）。简化调用星盘、八字、紫微、星宿、运势、AI 报告等接口的代码开发。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# apiworks-astro-node-sdk

Node.js SDK for ApiWorks 星盘 API（[www.apiworks.com](https://www.apiworks.com)）。支持星盘、八字、紫微、奇门遁甲、大六壬、星宿、运势、AI 报告等能力（SDK v1.1.0）。

## 功能概览

- **星盘 (Chart)**：本命盘、天象盘、行运盘、比较盘、组合盘、三限/次限/法达/日弧等
- **星座 (Sign)**：我的星座、星座列表、星座配对
- **运势 (Scope)**：日/周/月/年运势
- **星象事件 (Event)**：行运星象事件
- **紫微斗数 (Ziwei)**：本命盘、排盘、含解读的排盘
- **星宿 (Naks)**：27 星宿关系
- **八字 (Bazi)**：命盘、流盘、合盘、总结
- **三式 (Sanshi)**：奇门遁甲、大六壬 / 金口诀
- **报告 (Report)**：桃花、周运、年运、合盘、财运等 AI 报告
- **多语言**：请求体 / 查询参数 `lang`，支持 `zh-Hans`（默认）、`zh-Hant`、`en`（部分接口）

## 安装

```bash
npm install apiworks-astro-node-sdk
```

或从源码安装（在项目目录下）：

```bash
npm install
npm run build
```

## 依赖

- Node.js >= 14
- axios >= 1.6
- zod >= 3.22

## 凭证（App ID / App Key）

每个 `AstroCloudClient` 实例绑定**一对** `app_id` 与 `app_key`，该实例发出的全部请求都会带上这组凭证。

ApiWorks 网站上，不同产品线接口可能对应**不同**的 App ID / App Key（具体以网站开通为准）。请按你实际开通的凭证使用：需要多组凭证时，为每组各建一个 Client。

## 快速开始

### 基本用法

```javascript
const { AstroCloudClient } = require('apiworks-astro-node-sdk');

// 创建客户端
const client = new AstroCloudClient({
  app_id: 'your-app-id',
  app_key: 'your-app-key'
});
// base_url 默认为 https://cloud.apiworks.com/open/astro，如需可传入 base_url 覆盖

// 本命盘
async function getNatalChart() {
  try {
    const resp = await client.chart_natal({
      birth_dt: '1990-08-14 12:00:00',
      tz: 8,
      longitude: 116.4074,
      latitude: 39.9042
    });
    
    if (resp.code === 0 && resp.data) {
      console.log(resp.data.house, resp.data.planet);
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

getNatalChart();
```

### TypeScript 用法

```typescript
import { AstroCloudClient, SinglePointQry, ApiResp, AstroDataVo } from 'apiworks-astro-node-sdk';

// 创建客户端
const client = new AstroCloudClient({
  app_id: 'your-app-id',
  app_key: 'your-app-key'
});

// 本命盘
async function getNatalChart() {
  try {
    const qry: SinglePointQry = {
      birth_dt: '1990-08-14 12:00:00',
      tz: 8,
      longitude: 116.4074,
      latitude: 39.9042
    };
    
    const resp: ApiResp<AstroDataVo> = await client.chart_natal(qry);
    
    if (resp.code === 0 && resp.data) {
      console.log(resp.data.house, resp.data.planet);
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

getNatalChart();
```

### 更多示例

**八字命盘：**

```typescript
import { AstroCloudClient, BaziNatalQry, ApiResp, BaziNatalVO } from 'apiworks-astro-node-sdk';

const client = new AstroCloudClient({ app_id: '...', app_key: '...' });

async function getBaziNatal() {
  const qry: BaziNatalQry = {
    birth_dt: '1990-08-14 12:00:00',
    tz: 8,
    gender: 'male'
  };
  
  const resp: ApiResp<BaziNatalVO> = await client.bazi_natal(qry);
  if (resp.code === 0 && resp.data) {
    console.log(resp.data.pillars, resp.data.flow_decadal);
  }
}

getBaziNatal();
```

**紫微本命盘：**

```typescript
import { AstroCloudClient, ZiweiNatalQry, ApiResp, ZiweiNatalVo } from 'apiworks-astro-node-sdk';

const client = new AstroCloudClient({ app_id: '...', app_key: '...' });

async function getZiweiNatal() {
  const qry: ZiweiNatalQry = {
    birth_dt: '1999-10-17 21:00:00',
    tz: 8,
    gender: 'female'
  };
  
  const resp: ApiResp<ZiweiNatalVo> = await client.ziwei_natal(qry);
  if (resp.code === 0 && resp.data) {
    console.log(resp.data.natal.palaces, resp.data.patterns);
  }
}

getZiweiNatal();
```

**星宿关系：**

```typescript
import { AstroCloudClient, NaksQry, NaksBirthInfo, ApiResp, NaksVo } from 'apiworks-astro-node-sdk';

const client = new AstroCloudClient({ app_id: '...', app_key: '...' });

async function getNaksRelations() {
  const qry: NaksQry = {
    birth_info: {
      birth_dt: '1990-01-15 00:00:00',
      tz: 8
    },
    others_birth_info: [
      {
        birth_dt: '1992-03-20 00:00:00',
        tz: 8
      }
    ]
  };
  
  const resp: ApiResp<NaksVo> = await client.naks_relations(qry);
  if (resp.code === 0 && resp.data) {
    console.log(resp.data.natal_naks_info, resp.data.others_natal_relation);
  }
}

getNaksRelations();
```

**奇门遁甲 / 大六壬：**

```typescript
import { AstroCloudClient, QimenQry, LiurenQry } from 'apiworks-astro-node-sdk';

const client = new AstroCloudClient({ app_id: '...', app_key: '...' });

async function getSanshi() {
  // 时家拆补转盘
  const qm = await client.qimen({
    qry_dt: '1999-10-17 21:00:00',
    tz: 8,
    type: 'shijia',
    pai_method: 'zhuanpan',
    ju_method: 'chaibu',
    lang: 'zh-Hans',
  });
  if (qm.code === 0 && qm.data) {
    console.log(qm.data.ju_display, Object.keys(qm.data.jiu_gong));
  }

  // 大六壬
  const lr = await client.liuren({
    qry_dt: '1999-10-17 21:00:00',
    tz: 8,
    type: 'daliuren',
    gui_method: 'tian',
  });
  if (lr.code === 0 && lr.data) {
    console.log(lr.data.ge_ju, lr.data.si_ke, lr.data.san_chuan);
  }
}

getSanshi();
```

**双点星盘（行运/比较盘）：**

```typescript
import { AstroCloudClient, DoublePointQry, TimeAndLocation, ApiResp, AstroDataVo } from 'apiworks-astro-node-sdk';

const client = new AstroCloudClient({ app_id: '...', app_key: '...' });

async function getTransitChart() {
  const qry: DoublePointQry = {
    user_list: [
      {
        birth_dt: '1990-08-14 12:00:00',
        tz: 8,
        longitude: 116.4,
        latitude: 39.9
      },
      {
        birth_dt: '2025-02-26 12:00:00',
        tz: 8,
        longitude: 116.4,
        latitude: 39.9
      }
    ]
  };
  
  // 行运盘
  const transitResp: ApiResp<AstroDataVo> = await client.chart_transit(qry);
  // 比较盘
  const comparisonResp: ApiResp<AstroDataVo> = await client.chart_comparison(qry);
  
  if (transitResp.code === 0 && transitResp.data) {
    console.log(transitResp.data.planet, transitResp.data.house);
  }
}

getTransitChart();
```

**报告（桃花/合盘/周运等）：**

```typescript
import { AstroCloudClient, RomanticCreateQry, TimeAndLocation, ApiResp, AstroReportVo } from 'apiworks-astro-node-sdk';

const client = new AstroCloudClient({ app_id: '...', app_key: '...' });

async function createRomanticReport() {
  const qry: RomanticCreateQry = {
    user_birth_point: {
      birth_dt: '1990-01-01 13:14:15',
      tz: 8,
      longitude: 116.4,
      latitude: 39.9
    },
    user_current_point: {
      birth_dt: '2025-11-26 13:14:15',
      tz: 8,
      longitude: 116.4,
      latitude: 39.9
    },
    user_id: 'user-123'
  };
  
  const resp: ApiResp<AstroReportVo> = await client.report_romantic(qry);
  if (resp.code === 0 && resp.data && resp.data.serial_no) {
    const serial_no = resp.data.serial_no; // 可用 report_get / report_get_html 拉取报告
    console.log('Report serial number:', serial_no);
  }
}

createRomanticReport();
```

## API 响应格式

所有接口均返回 `ApiResp<T>` 类型，包含 `code`、`msg`、`data`、`exe_time` 字段，其中 `data` 为与接口对应的响应类型（如 `BaziNatalVO`、`NaksVo`、`AstroDataVo` 等）：

```typescript
const resp: ApiResp<BaziNatalVO> = await client.bazi_natal(qry);
if (resp.code === 0 && resp.data) {
  const data: BaziNatalVO = resp.data; // 强类型，IDE 可补全
  console.log(data.pillars);
}
```

## 验证 SDK 是否可用

用真实接口调用一次本命盘，确认网络与凭证正常：

```bash
# 在项目根目录，先安装依赖
npm install

# 设置你的 app_id / app_key 后执行（不要提交到仓库）
export APIWORKS_APP_ID="你的app_id"
export APIWORKS_APP_KEY="你的app_key"
npm run verify
```

成功会打印 `验证通过，SDK 可用。`；若 `code != 0` 或报错，请检查凭证与网络。

## 项目结构

```
apiworks-astro-node-sdk/
├── src/
│   ├── apiworks_astro_sdk/
│   │   ├── models/
│   │   │   ├── common.ts            # ApiResp, TimeAndLocation
│   │   │   ├── requests.ts          # 各类请求模型（含 lang / 奇门 / 六壬）
│   │   │   ├── responses.ts         # 各类响应模型
│   │   │   ├── sanshi_responses.ts  # 奇门 / 大六壬响应 VO
│   │   │   └── index.ts             # 模型导出
│   │   ├── client.ts                # AstroCloudClient
│   │   └── index.ts                 # 客户端导出
│   └── index.ts                     # 主导出
├── scripts/
│   └── verify_sdk.ts                # SDK 验证脚本
├── package.json
├── tsconfig.json
└── README.md
```

## License

MIT