amlich-api 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,10 @@
 # amlich-api
 
-TypeScript/JavaScript SDK để gọi AmLich API.
+TypeScript SDK cho AmLich API.
 
 - Base URL mặc định: `https://amlich.giaphahobe.vn`
 - API prefix mặc định: `/api/v1`
-- Tương thích Node.js >= 18 (dùng `fetch` built-in) và browser
+- Chạy trên Node.js >= 18 (fetch built-in) và browser
 
 ## Cài đặt
 
@@ -12,61 +12,119 @@ TypeScript/JavaScript SDK để gọi AmLich API.
 npm i amlich-api
 ```
 
-## Sử dụng nhanh
+## Khởi tạo client
 
 ```ts
 import { AmLichClient } from "amlich-api";
 
-const api = new AmLichClient();
-
-const today = await api.today(7);
-console.log(today);
+const api = new AmLichClient({
+  baseUrl: "https://amlich.giaphahobe.vn",
+  apiPrefix: "/api/v1",
+  timeoutMs: 15000,
+});
 ```
 
-## API
+Constructor options:
 
-### `new AmLichClient(options?)`
+- `baseUrl?: string`
+- `apiPrefix?: string`
+- `headers?: Record<string, string>`
+- `fetchImpl?: typeof fetch`
+- `timeoutMs?: number`
 
-Options:
+## Methods
 
-- `baseUrl?: string` (default: `https://amlich.giaphahobe.vn`)
-- `apiPrefix?: string` (default: `/api/v1`)
-- `headers?: Record<string, string>`
-- `fetchImpl?: typeof fetch` (truyền custom fetch nếu môi trường không có sẵn)
-- `timeoutMs?: number` (default: `15000`)
+### Calendar core
 
-### `today(tz?: number): Promise<TodayResponse>`
+```ts
+await api.today(7);
+await api.day("2026-02-21", 7, 22);
+await api.month(2026, 2, 7);
+```
 
-Gọi `GET /today`.
+- `today(tz?: number)` -> `GET /today`
+- `day(date: string, tz?: number, hour?: number)` -> `GET /day`
+- `month(year: number, month: number, tz?: number)` -> `GET /month`
 
-### `day(date: string, tz?: number, hour?: number): Promise<DayResponse>`
+### Tra cứu can chi / tương hợp
 
-Gọi `GET /day?date=YYYY-MM-DD&tz=7&hour=23`.
+```ts
+await api.napam("Giáp Tý");
+await api.chiRelations("Tý");
+await api.compat("2026-02-21", 7, 1987);
+```
 
-Nếu server hiện tại chưa expose endpoint này, SDK sẽ throw `AmLichError` với `status = 404`.
+- `napam(name: string)` -> `GET /napam`
+- `chiRelations(chi: string)` -> `GET /chi/relations`
+- `compat(date: string, tz?: number, userYear?: number)` -> `GET /compat`
 
-### `month(year: number, month: number, tz?: number): Promise<MonthResponse>`
+### Tiết khí / ngày kỵ / sao / thần sát
 
-Gọi `GET /month?year=2026&month=2&tz=7`.
+```ts
+await api.tietKhi("2026-02-21", 7);
+await api.tietKhiYear(2026, 7);
+await api.ngayKy("2026-02-21", 7);
+await api.saoTu("2026-02-21", 7);
+await api.thanSat("2026-02-21", 7);
+```
 
-Nếu server hiện tại chưa expose endpoint này, SDK sẽ throw `AmLichError` với `status = 404`.
+- `tietKhi(date: string, tz?: number)` -> `GET /tietkhi`
+- `tietKhiYear(year: number, tz?: number)` -> `GET /tietkhi/year`
+- `ngayKy(date: string, tz?: number)` -> `GET /ngayky`
+- `saoTu(date: string, tz?: number)` -> `GET /saotu`
+- `thanSat(date: string, tz?: number)` -> `GET /thansat`
 
-## Override baseUrl
+### Warnings / Pick
 
 ```ts
-import { AmLichClient } from "amlich-api";
+await api.warnings({
+  date: "2026-02-21",
+  tz: 7,
+  userYear: 1987,
+  purpose: "khaisuong",
+  ruleset: "vn-basic",
+});
 
-const api = new AmLichClient({
-  baseUrl: "https://example.com",
-  apiPrefix: "/api/v1",
-  headers: {
-    "x-api-key": "your-key",
-  },
-  timeoutMs: 10000,
+await api.pick({
+  from: "2026-02-20",
+  to: "2026-03-15",
+  tz: 7,
+  purpose: "khaisuong",
+  userYear: 1987,
+  limit: 5,
+  maxDays: 92,
+  ruleset: "vn-basic",
 });
 ```
 
-## Xử lý lỗi `AmLichError`
+- `warnings(query)` -> `GET /warnings`
+- `pick(query)` -> `GET /pick`
+
+### Convert (POST)
+
+```ts
+await api.solarToLunar({
+  year: 2026,
+  month: 2,
+  day: 21,
+  tz: 7,
+});
+
+await api.lunarToSolar({
+  year: 2026,
+  month: 1,
+  day: 14,
+  isLeap: false,
+  tz: 7,
+});
+```
+
+- `solarToLunar(payload)` -> `POST /convert/solar-to-lunar`
+- `lunarToSolar(payload)` -> `POST /convert/lunar-to-solar`
+
+## Error handling
+
+SDK throw `AmLichError` khi timeout/network error hoặc HTTP status không thành công.
 
 ```ts
 import { AmLichClient, AmLichError } from "amlich-api";
@@ -74,19 +132,20 @@ import { AmLichClient, AmLichError } from "amlich-api";
 const api = new AmLichClient();
 
 try {
-  const data = await api.today(7);
-  console.log(data);
+  await api.today(7);
 } catch (error) {
   if (error instanceof AmLichError) {
-    console.error("Status:", error.status);
-    console.error("Message:", error.message);
-    console.error("Data:", error.data);
-  } else {
-    console.error("Unknown error:", error);
+    console.error(error.status);
+    console.error(error.message);
+    console.error(error.data);
   }
 }
 ```
 
+## Type notes
+
+Package dùng kiểu `loose but structured`: có field chính + `[k: string]: unknown` để thích ứng khi API thay đổi schema.
+
 ## Development
 
 ```bash
@@ -95,47 +154,6 @@ npm run dev
 npm run build
 ```
 
-## Publish npm
-
-1. Đăng nhập npm:
-
-```bash
-npm login
-```
-
-2. Kiểm tra tên package có trống không:
-
-```bash
-npm view amlich-api version
-```
-
-- Nếu command báo lỗi `404 Not Found`, tên `amlich-api` chưa bị chiếm.
-- Nếu có version trả về, tên đã bị chiếm.
-
-3. Publish package:
-
-```bash
-npm publish --access public
-```
-
-### Fallback khi name bị chiếm
-
-Đổi sang scoped package, ví dụ `@your-scope/amlich-api`:
-
-1. Cập nhật trường `name` trong `package.json`:
-
-```json
-{
-  "name": "@your-scope/amlich-api"
-}
-```
-
-2. Publish lại:
-
-```bash
-npm publish --access public
-```
-
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 type UnknownFields = {
     [key: string]: unknown;
 };
+type Purpose = "khaisuong" | "cuoihoi" | "dongtho" | "nhaptrach" | "xuat_hanh" | (string & {});
 type TodayResponse = {
     date: string;
 } & UnknownFields;
@@ -14,6 +15,99 @@ type MonthResponse = {
     month: number;
     days: unknown[];
 } & UnknownFields;
+type NapAmResponse = {
+    name?: string;
+    value?: string;
+} & UnknownFields;
+type ChiRelationsResponse = {
+    chi?: string;
+    tamHop?: string[];
+    lucXungWith?: string;
+} & UnknownFields;
+type CompatResponse = {
+    user?: unknown;
+    day?: unknown;
+    relations?: unknown;
+    verdict?: "good" | "neutral" | "bad" | string;
+} & UnknownFields;
+type TietKhiResponse = {
+    index?: number;
+    name?: string;
+    startAt?: string;
+    endAt?: string;
+    next?: unknown;
+    secondsToNext?: number;
+} & UnknownFields;
+type TietKhiYearResponse = {
+    year?: number;
+    terms?: unknown[];
+} & UnknownFields;
+type NgayKyResponse = {
+    date?: string;
+    items?: unknown[];
+} & UnknownFields;
+type SaoTuResponse = {
+    jd?: number;
+    sao28Tu?: unknown;
+} & UnknownFields;
+type ThanSatResponse = {
+    date?: string;
+    items?: unknown[];
+} & UnknownFields;
+type WarningItem = {
+    type?: string;
+    code?: string;
+    name?: string;
+    level?: "good" | "warn" | "avoid" | "bad" | string;
+    reason?: string;
+} & UnknownFields;
+type WarningsResponse = {
+    input?: unknown;
+    level?: "good" | "warn" | "bad" | string;
+    summary?: string[];
+    items?: WarningItem[];
+} & UnknownFields;
+type PickResultItem = {
+    date?: string;
+    weekdayName?: string;
+    score?: number;
+    verdict?: "good" | "ok" | "avoid" | string;
+    reasons?: string[];
+    highlights?: unknown;
+} & UnknownFields;
+type PickResponse = {
+    input?: unknown;
+    results?: PickResultItem[];
+    meta?: unknown;
+} & UnknownFields;
+type ConvertRequest = {
+    year: number;
+    month: number;
+    day: number;
+    tz?: number;
+    isLeap?: boolean;
+} & UnknownFields;
+type ConvertResponse = {
+    input?: unknown;
+    output?: unknown;
+} & UnknownFields;
+type WarningsQuery = {
+    date: string;
+    tz?: number;
+    userYear?: number;
+    purpose?: Purpose;
+    ruleset?: string;
+};
+type PickQuery = {
+    from: string;
+    to: string;
+    purpose: Purpose;
+    tz?: number;
+    userYear?: number;
+    limit?: number;
+    maxDays?: number;
+    ruleset?: string;
+};
 type AmLichClientOptions = {
     baseUrl?: string;
     apiPrefix?: string;
@@ -40,9 +134,23 @@ declare class AmLichClient {
     today(tz?: number): Promise<TodayResponse>;
     day(date: string, tz?: number, hour?: number): Promise<DayResponse>;
     month(year: number, month: number, tz?: number): Promise<MonthResponse>;
+    napam(name: string): Promise<NapAmResponse>;
+    chiRelations(chi: string): Promise<ChiRelationsResponse>;
+    compat(date: string, tz?: number, userYear?: number): Promise<CompatResponse>;
+    tietKhi(date: string, tz?: number): Promise<TietKhiResponse>;
+    tietKhiYear(year: number, tz?: number): Promise<TietKhiYearResponse>;
+    ngayKy(date: string, tz?: number): Promise<NgayKyResponse>;
+    saoTu(date: string, tz?: number): Promise<SaoTuResponse>;
+    thanSat(date: string, tz?: number): Promise<ThanSatResponse>;
+    warnings(query: WarningsQuery): Promise<WarningsResponse>;
+    pick(query: PickQuery): Promise<PickResponse>;
+    solarToLunar(payload: ConvertRequest): Promise<ConvertResponse>;
+    lunarToSolar(payload: ConvertRequest): Promise<ConvertResponse>;
+    private get;
+    private post;
     private buildUrl;
     private parseResponseBody;
     private request;
 }
 
-export { AmLichClient, type AmLichClientOptions, AmLichError, type DayResponse, type MonthResponse, type TodayResponse };
+export { AmLichClient, type AmLichClientOptions, AmLichError, type ChiRelationsResponse, type CompatResponse, type ConvertRequest, type ConvertResponse, type DayResponse, type MonthResponse, type NapAmResponse, type NgayKyResponse, type PickQuery, type PickResponse, type SaoTuResponse, type ThanSatResponse, type TietKhiResponse, type TietKhiYearResponse, type TodayResponse, type WarningsQuery, type WarningsResponse };

package/dist/index.js

@@ -38,24 +38,95 @@ var AmLichClient = class {
     this.timeoutMs = timeoutMs;
   }
   today(tz) {
-    return this.request("/today", {
+    return this.get("/today", {
       tz
     });
   }
   day(date, tz, hour) {
-    return this.request("/day", {
+    return this.get("/day", {
       date,
       tz,
       hour
     });
   }
   month(year, month, tz) {
-    return this.request("/month", {
+    return this.get("/month", {
       year,
       month,
       tz
     });
   }
+  napam(name) {
+    return this.get("/napam", { name });
+  }
+  chiRelations(chi) {
+    return this.get("/chi/relations", { chi });
+  }
+  compat(date, tz, userYear) {
+    return this.get("/compat", {
+      date,
+      tz,
+      userYear
+    });
+  }
+  tietKhi(date, tz) {
+    return this.get("/tietkhi", {
+      date,
+      tz
+    });
+  }
+  tietKhiYear(year, tz) {
+    return this.get("/tietkhi/year", {
+      year,
+      tz
+    });
+  }
+  ngayKy(date, tz) {
+    return this.get("/ngayky", {
+      date,
+      tz
+    });
+  }
+  saoTu(date, tz) {
+    return this.get("/saotu", {
+      date,
+      tz
+    });
+  }
+  thanSat(date, tz) {
+    return this.get("/thansat", {
+      date,
+      tz
+    });
+  }
+  warnings(query) {
+    return this.get("/warnings", query);
+  }
+  pick(query) {
+    return this.get("/pick", query);
+  }
+  solarToLunar(payload) {
+    return this.post(
+      "/convert/solar-to-lunar",
+      payload
+    );
+  }
+  lunarToSolar(payload) {
+    return this.post(
+      "/convert/lunar-to-solar",
+      payload
+    );
+  }
+  get(path, query) {
+    return this.request("GET", path, {
+      query
+    });
+  }
+  post(path, body) {
+    return this.request("POST", path, {
+      body
+    });
+  }
   buildUrl(path, query) {
     const normalizedPrefix = this.apiPrefix.startsWith("/") ? this.apiPrefix : `/${this.apiPrefix}`;
     const normalizedPath = path.startsWith("/") ? path : `/${path}`;
@@ -77,21 +148,30 @@ var AmLichClient = class {
       return text;
     }
   }
-  async request(path, query) {
-    const url = this.buildUrl(path, query);
+  async request(method, path, options) {
+    const url = this.buildUrl(path, options?.query);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    const headers = {
+      ...this.headers
+    };
+    let bodyText;
+    if (method === "POST") {
+      headers["content-type"] = headers["content-type"] ?? "application/json";
+      bodyText = JSON.stringify(options?.body ?? {});
+    }
     let response;
     try {
       response = await this.fetchImpl(url, {
-        method: "GET",
-        headers: this.headers,
-        signal: controller.signal
+        method,
+        headers,
+        signal: controller.signal,
+        body: bodyText
       });
     } catch (error) {
       if (error instanceof DOMException && error.name === "AbortError") {
         throw new AmLichError(
-          `Request timed out after ${this.timeoutMs}ms while calling ${url.pathname}`
+          `Request timed out after ${this.timeoutMs}ms while calling ${method} ${url.pathname}`
         );
       }
       throw new AmLichError(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amlich-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript client SDK for AmLich API",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,4 +41,4 @@
     "tsup": "^8.4.0",
     "typescript": "^5.8.2"
   }
-}
+}