@khang07/zing-mp3-api 1.0.1 → 1.3.2

package/README.md

@@ -1,323 +1,442 @@
-# @khang07/zing-mp3-api
-
-Node.js library để lấy stream nhạc và video từ Zing MP3 dưới dạng `Readable` stream.
-
-Package này hiện tập trung vào 2 tác vụ chính:
-
-- Lấy **nhạc** theo ID và trả về stream audio
-- Lấy **video** theo ID và trả về stream video HLS
-
-Library build sẵn cho cả **ESM** và **CommonJS**, có type cho TypeScript.
-
-## Tính năng
-
-- Export sẵn `client` dùng ngay
-- Có thể tự tạo `new Client()` để chỉnh tốc độ stream/buffer
-- Trả về `Readable` stream để pipe thẳng ra file, HTTP response, Discord voice pipeline, hoặc xử lý tiếp
-- Có cookie jar nội bộ để giữ cookie giữa các request
-- Có chữ ký request nội bộ cho API đang dùng
-- Hỗ trợ ESM, CJS, TypeScript
-
-## Cài đặt
-
-```bash
-npm install @khang07/zing-mp3-api
-```
-
-hoặc
-
-```bash
-bun add @khang07/zing-mp3-api
-```
-
-## Yêu cầu môi trường
-
-Package này chạy cho **Node.js**, không dành cho browser vì dùng:
-
-- `node:stream`
-- `node:crypto`
-- `axios` với Node adapter
-- `m3u8stream`
-
-## Dùng nhanh
-
-### ESM
-
-```ts
-import client from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-const writer = createWriteStream("music.mp3");
-const stream = await client.music("MUSIC_ID");
-
-stream.pipe(writer);
-```
-
-### ESM với named import
-
-```ts
-import { client, Client } from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-const musicWriter = createWriteStream("music.mp3");
-client.musicSyncLike("MUSIC_ID").pipe(musicWriter);
-
-const customClient = new Client({
-    maxRate: [256 * 1024, 64 * 1024]
-});
-
-const videoWriter = createWriteStream("video.bin");
-const videoStream = await customClient.video("VIDEO_ID");
-videoStream.pipe(videoWriter);
-```
-
-### CommonJS
-
-```js
-const { client, Client } = require("@khang07/zing-mp3-api");
-const { createWriteStream } = require("node:fs");
-
-const writer = createWriteStream("music.mp3");
-client.musicSyncLike("MUSIC_ID").pipe(writer);
-```
-
-## API
-
-### `new Client(options?)`
-
-Tạo client mới.
-
-```ts
-import { Client } from "@khang07/zing-mp3-api";
-
-const client = new Client({
-    maxRate: [100 * 1024, 16 * 1024]
-});
-```
-
-#### `ClientOptions`
-
-```ts
-interface ClientOptions {
-    maxRate?: [download?: number, highWaterMark?: number];
-}
-```
-
-Ý nghĩa:
-
-- `download`: giới hạn tốc độ download cho request stream
-- `highWaterMark`: buffer size cho `PassThrough` của các hàm `SyncLike`
-
-Giá trị mặc định:
-
-```ts
-[100 * 1024, 16 * 1024]
-```
-
-## Các method
-
-### `await client.music(musicID)`
-
-Trả về `Promise<Readable>` cho audio stream.
-
-```ts
-import client from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-const output = createWriteStream("music.mp3");
-const stream = await client.music("ZZEEOZEC");
-
-stream.pipe(output);
-```
-
-Ghi chú:
-
-- Method này gọi API `/api/v2/song/get/streaming`
-- Hiện tại code lấy URL tại `data[128]`
-- Nghĩa là implementation hiện tại đang dùng nhánh stream **128 kbps**
-
-### `client.musicSyncLike(musicID)`
-
-Trả về `Readable` ngay để có thể pipe trực tiếp, phù hợp khi bạn muốn viết ngắn hơn.
-
-```ts
-import client from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-client.musicSyncLike("ZZEEOZEC").pipe(createWriteStream("music.mp3"));
-```
-
-### `await client.video(videoID)`
-
-Trả về `Promise<Readable>` cho video stream.
-
-```ts
-import client from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-const output = createWriteStream("video.bin");
-const stream = await client.video("ZZEEOZEC");
-
-stream.pipe(output);
-```
-
-Ghi chú quan trọng:
-
-- Method này gọi API `/api/v2/page/get/video`
-- Hiện tại code chỉ lấy `streaming.hls["360p"]`
-- Đây là **HLS stream** lấy qua `m3u8stream`
-- Library **không transcode**, **không remux**, **không ép sang MP4 thật**
-- Vì vậy bạn nên xem dữ liệu trả về là **stream media thô từ HLS**, không nên mặc định coi nó luôn là file `.mp4` chuẩn
-
-### `client.videoSyncLike(videoID)`
-
-Trả về `Readable` ngay để pipe trực tiếp.
-
-```ts
-import client from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-client.videoSyncLike("ZZEEOZEC").pipe(createWriteStream("video.bin"));
-```
-
-## Bắt lỗi
-
-Khi có lỗi, code ném ra error với các field thực tế đang có trong implementation:
-
-- `name`: `ZING_MP3_ERROR`
-- `message`
-- `code`
-- `status` (nếu có)
-- `cause` (nếu có)
-
-Các mã lỗi đang xuất hiện trong source:
-
-- `ERROR_INVALID_ID`
-- `ERROR_MUSIC_NOT_FOUND`
-- `ERROR_MUSIC_VIP_ONLY`
-- `ERROR_VIDEO_NOT_FOUND`
-- `ERROR_STREAM_URL_NOT_FOUND`
-- `ERROR_STREAM_DOWNLOAD`
-- `ERROR_MUSIC_FETCH`
-- `ERROR_VIDEO_FETCH`
-
-Ví dụ:
-
-```ts
-import client from "@khang07/zing-mp3-api";
-import { createWriteStream } from "node:fs";
-
-try {
-    const stream = await client.music("ZZEEOZEC");
-    const writer = createWriteStream("music.mp3");
-
-    stream.on("error", (error) => {
-        console.error("Stream error:", error);
-    });
-
-    writer.on("error", (error) => {
-        console.error("Write error:", error);
-    });
-
-    stream.pipe(writer);
-} catch (error) {
-    console.error(error);
-}
-```
-
-## Dùng với HTTP server
-
-```ts
-import http from "node:http";
-import client from "@khang07/zing-mp3-api";
-
-const server = http.createServer(async (_req, res) => {
-    try {
-        const stream = await client.music("ZZEEOZEC");
-
-        res.writeHead(200, {
-            "Content-Type": "audio/mpeg"
-        });
-
-        stream.on("error", () => {
-            if (!res.headersSent)
-                res.writeHead(500);
-
-            res.end("Stream failed");
-        });
-
-        stream.pipe(res);
-    } catch {
-        res.writeHead(500);
-        res.end("Failed to fetch music");
-    }
-});
-
-server.listen(3000);
-```
-
-## Build từ source
-
-Project đang dùng TypeScript + Rollup + API Extractor.
-
-```bash
-bun install
-bun run build
-```
-
-Output build:
-
-- `dist/esm` → bản ESM
-- `dist/cjs` → bản CommonJS
-- `dist/types` → type declarations gộp
-
-Các script hiện có:
-
-```bash
-bun run build:esm
-bun run build:cjs
-bun run build:types
-bun run build
-```
-
-## Cấu trúc dự án
-
-```text
-source/
-  index.ts
-  types/
-  utils/
-dist/
-  esm/
-  cjs/
-  types/
-```
-
-## Ghi chú triển khai hiện tại
-
-Có vài điểm cần lưu ý:
-
-- Chưa có API search public trong `Client` dù đang export type `SearchCategory`
-- Video hiện mới lấy nhánh `360p`
-- Music hiện mới lấy nhánh `128kps`
-- Package phụ thuộc vào cấu trúc API/cookie/signature hiện tại của Zing MP3, nên nếu upstream đổi thì cần cập nhật source
-
-## Ghi chú về file test trong repo
-
-Trong repo hiện có `test/index.js` và `test/index.cjs`, nhưng chúng đang import từ `"zing-mp3-api"`.
-
-Khi publish theo `package.json` hiện tại, import đúng cho người dùng ngoài sẽ là:
-
-```js
-import { client } from "@khang07/zing-mp3-api";
-```
-
-hoặc:
-
-```js
-const { client } = require("@khang07/zing-mp3-api");
-```
-
-## License
-
-Xem tại [LICENSE](https://github.com/GiaKhang1810/zing-mp3-api#license)
+# `@khang07/zing-mp3-api`
+
+The basic APIs provide the features of ZingMp3.
+
+## Features
+
+* Search songs, videos, playlists, and artists
+* Fetch playlist, artist, and song details
+* Get readable streams for music and video
+* Accept raw resource tokens or `URL` values for resource-based methods
+* Provide a cookie jar utility through a public subpath export
+* Ship ESM and CommonJS entry points
+
+## Installation
+
+```bash
+npm install @khang07/zing-mp3-api
+```
+
+## Public Exports
+
+### Root export
+
+#### Runtime exports
+
+* `default`: a pre-created `Client` instance
+* `Client`: the client class
+
+#### Type exports
+
+* `ClientOptions`
+* `PlayList`
+* `Artist`
+* `Media`
+* `SearhMedia`
+* `SearchPlayList`
+* `Cookies` *(type-only export from the root entry)*
+
+### Public subpath exports
+
+```ts
+import { Cookies } from "@khang07/zing-mp3-api/utils/cookies";
+import { createSignature } from "@khang07/zing-mp3-api/utils/encrypt";
+import { Lapse } from "@khang07/zing-mp3-api/utils/lapse";
+```
+
+## Import
+
+### ESM
+
+```ts
+import client, { Client } from "@khang07/zing-mp3-api";
+```
+
+### CommonJS
+
+```js
+const zing = require("@khang07/zing-mp3-api");
+
+const client = zing.default;
+const { Client } = zing;
+```
+
+## Basic Usage
+
+### Use the default client
+
+```ts
+import client from "@khang07/zing-mp3-api";
+
+const items = await client.searchMusic("Do For Love Bray");
+console.log(items[0]);
+```
+
+### Create a client
+
+```ts
+import { Client } from "@khang07/zing-mp3-api";
+import { Cookies } from "@khang07/zing-mp3-api/utils/cookies";
+
+const client = new Client({
+    maxLoad: 16 * 1024,
+    maxHighWaterMark: 16 * 1024,
+    userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
+    jar: new Cookies()
+});
+```
+
+### Fetch a playlist from a URL
+
+```ts
+import client from "@khang07/zing-mp3-api";
+
+const playlist = await client.playlist("https://zingmp3.vn/album/example/ZWZB9WAB.html");
+console.log(playlist.name);
+console.log(playlist.mediaCount);
+```
+
+### Fetch artist details
+
+```ts
+import client from "@khang07/zing-mp3-api";
+
+const artist = await client.artist("https://zingmp3.vn/Obito");
+console.log(artist.name);
+console.log(artist.followCount);
+```
+
+### Download a music stream
+
+```ts
+import { createWriteStream } from "node:fs";
+import client from "@khang07/zing-mp3-api";
+
+const items = await client.searchMusic("Do For Love Bray");
+const stream = await client.music(items[0].id);
+
+stream.pipe(createWriteStream("music.mp3"));
+```
+
+### Download a video stream
+
+```ts
+import { createWriteStream } from "node:fs";
+import client from "@khang07/zing-mp3-api";
+
+const items = await client.searchVideo("Do For Love Bray");
+const stream = await client.video(items[0].id);
+
+stream.pipe(createWriteStream("video.ts"));
+```
+
+### Use the immediate stream-returning methods
+
+```ts
+import { createWriteStream } from "node:fs";
+import client from "@khang07/zing-mp3-api";
+
+const stream = client.musicSync("ZWZB9WAB");
+stream.pipe(createWriteStream("music.mp3"));
+```
+
+### Handle library errors
+
+```ts
+import client from "@khang07/zing-mp3-api";
+import { Lapse } from "@khang07/zing-mp3-api/utils/lapse";
+
+try {
+    await client.playlist("");
+} catch (error) {
+    if (error instanceof Lapse) {
+        console.error(error.name);
+        console.error(error.code);
+        console.error(error.status);
+    }
+}
+```
+
+## API Reference
+
+## `new Client(options?)`
+
+Creates a new client instance.
+
+### `ClientOptions`
+
+| Field              | Type      | Default                                                                                                              |
+| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------- |
+| `maxLoad`          | `number`  | `1024 * 1024`                                                                                                          |
+| `maxHighWaterMark` | `number`  | `16 * 1024`                                                                                                            |
+| `userAgent`        | `string`  | `Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3` |
+| `jar`              | `Cookies` | `new Cookies()`                                                                                                      |
+
+`maxLoad` is passed to Axios as `maxRate`.
+
+`maxHighWaterMark` is used as the `highWaterMark` when `musicSync()` and `videoSync()` create a `PassThrough` stream.
+
+## `Client.getIDFromURL(url)`
+
+```ts
+static getIDFromURL(url: string): string
+```
+
+Extracts a resource token from a ZingMp3 URL.
+
+It throws `ERROR_INVALID_URL` when the input is not a non-empty string or when no token can be extracted.
+
+## Instance Methods
+
+| Method                  | Returns                                                                                                           | Description                                                                     |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `video(videoID)`        | `Promise<Readable>`                                                                                               | Fetches a video stream. Accepts a raw token, URL string, or `URL`.              |
+| `videoSync(videoID)`    | `Readable`                                                                                                        | Returns a `PassThrough` immediately and pipes the fetched video stream into it. |
+| `music(musicID)`        | `Promise<Readable>`                                                                                               | Fetches a music stream. Accepts a raw token, URL string, or `URL`.              |
+| `musicSync(musicID)`    | `Readable`                                                                                                        | Returns a `PassThrough` immediately and pipes the fetched music stream into it. |
+| `playlist(playlistID)`  | `Promise<PlayList>`                                                                                               | Fetches playlist details. Accepts a raw token, URL string, or `URL`.            |
+| `artist(aliasID)`       | `Promise<Artist>`                                                                                                 | Fetches artist details. Accepts an alias token, URL string, or `URL`.           |
+| `mediaDetails(mediaID)` | `Promise<Media>`                                                                                                  | Fetches song details. Accepts a raw token, URL string, or `URL`.                |
+| `searchMusic(query)`    | `Promise<Media[]>`                                                                                                | Searches songs.                                                                 |
+| `searchVideo(query)`    | `Promise<SearhMedia[]>`                                                                                           | Searches videos.                                                                |
+| `searchList(query)`     | `Promise<SearchPlayList[]>`                                                                                       | Searches playlists.                                                             |
+| `searchArtist(query)`   | `Promise<SearchArtist[]>` | Searches artists.                                                               |
+
+### Method notes
+
+* `video()` selects `720p` first, then falls back to `360p`.
+* `music()` selects `320` first when available and not equal to `"VIP"`, then falls back to `128`.
+* When the music API returns `err === -1150`, `music()` retries the extra music endpoint up to 4 times and throws `ERROR_MUSIC_VIP_ONLY` if it still cannot resolve a playable URL.
+* `searchMusic()`, `searchVideo()`, `searchList()`, and `searchArtist()` always request `page: 1` and `count: 20`.
+
+## Public Types
+
+### `Artist`
+
+```ts
+interface Artist {
+    alias: string;
+    birthday: string;
+    biography: string;
+    followCount: number;
+    name: string;
+    national: string;
+    realname: string;
+    thumbnail: {
+        w240: string;
+        w600: string;
+    };
+}
+```
+
+### `Media`
+
+```ts
+interface Media {
+    id: string;
+    name: string;
+    alias: string;
+    isOffical: boolean;
+    username: string;
+    artists: Array<{
+        alias: string;
+        followCount?: number;
+        name: string;
+        thumbnail: {
+            w240: string;
+            w600: string;
+        };
+    }>;
+    isWorldWide: boolean;
+    thumbnail: {
+        w94: string;
+        w240: string;
+    };
+    duration: number;
+    isPrivate: boolean;
+    releaseDate: number;
+    album: {
+        id: string;
+        name: string;
+        isOffical: boolean;
+        releaseDate: string;
+        releasedAt: number;
+        artists: Array<{
+            alias: string;
+            followCount?: number;
+            name: string;
+            thumbnail: {
+                w240: string;
+                w600: string;
+            };
+        }>;
+        thumbnail: {
+            w165: string;
+        };
+    };
+    hasLyric: boolean;
+}
+```
+
+### `SearhMedia`
+
+```ts
+type SearhMedia = Omit<Media, "album">;
+```
+
+### `PlayList`
+
+```ts
+interface PlayList {
+    id: string;
+    name: string;
+    alias: string;
+    artists: Array<{
+        alias: string;
+        followCount?: number;
+        name: string;
+        thumbnail: {
+            w240: string;
+            w600: string;
+        };
+    }>;
+    description: string;
+    duration: number;
+    isOffical: boolean;
+    isPrivate: boolean;
+    isSingle: boolean;
+    likeCount: number;
+    listenCount: number;
+    media: Media[];
+    mediaCount: number;
+    releaseDate: string;
+    releasedAt: number;
+    thumbnail: {
+        w165: string;
+        w320: string;
+    };
+    updatedAt: number;
+}
+```
+
+### `SearchPlayList`
+
+```ts
+type SearchPlayList = Omit<
+    PlayList,
+    "updatedAt" | "mediaCount" | "listenCount" | "likeCount" | "duration" | "description" | "media"
+>;
+```
+
+## `Cookies`
+
+Import from `@khang07/zing-mp3-api/utils/cookies`.
+
+### Methods
+
+| Method                                 | Returns                  |
+| -------------------------------------- | ------------------------ |
+| `setCookie(setCookie, requestUrl)`     | `void`                   |
+| `setCookies(setCookies, requestUrl)`   | `void`                   |
+| `getCookies(requestUrl)`               | `CookieRecord[]`         |
+| `getCookieHeader(requestUrl)`          | `string`                 |
+| `applyToHeaders(requestUrl, headers?)` | `Record<string, string>` |
+| `deleteCookie(domain, path, name)`     | `void`                   |
+| `cleanup()`                            | `void`                   |
+| `toJSON()`                             | `CookieRecord[]`         |
+| `fromJSON(cookies)`                    | `void`                   |
+
+### Cookie record shape
+
+```ts
+interface CookieRecord {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expiresAt?: number;
+    secure: boolean;
+    httpOnly: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+    hostOnly: boolean;
+}
+```
+
+### Example
+
+```ts
+import { Cookies } from "@khang07/zing-mp3-api/utils/cookies";
+
+const jar = new Cookies();
+jar.setCookie("sid=abc; Path=/; HttpOnly", "https://zingmp3.vn/");
+
+console.log(jar.getCookieHeader("https://zingmp3.vn/"));
+```
+
+## `createSignature(uri, params, secret)`
+
+Import from `@khang07/zing-mp3-api/utils/encrypt`.
+
+```ts
+function createSignature(uri: string, params: string, secret: string): string
+```
+
+Generates the request signature used by the client.
+
+## `Lapse`
+
+Import from `@khang07/zing-mp3-api/utils/lapse`.
+
+```ts
+class Lapse extends Error {
+    code: string;
+    status?: number;
+    cause?: unknown;
+}
+```
+
+### Constructor
+
+```ts
+new Lapse(message: string, code: string, status?: number, cause?: unknown)
+```
+
+### Properties
+
+* `name`: always set to `"ZING_MP3_ERROR"`
+* `message`: inherited from `Error`
+* `code`: library error code
+* `status`: optional status or API error value
+* `cause`: optional original error or response payload
+
+## Error Codes
+
+| Code                         | Used by                                                            |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `ERROR_INVALID_URL`          | `Client.getIDFromURL()`                                            |
+| `ERROR_INVALID_ID`           | `video()`, `music()`, `playlist()`, `artist()`, `mediaDetails()`   |
+| `ERROR_INVALID_QUERY`        | `searchMusic()`, `searchVideo()`, `searchList()`, `searchArtist()` |
+| `ERROR_VIDEO_NOT_FOUND`      | `video()`                                                          |
+| `ERROR_VIDEO_FETCH`          | `video()`, `videoSync()`                                           |
+| `ERROR_MUSIC_VIP_ONLY`       | `music()`                                                          |
+| `ERROR_MUSIC_FETCH`          | `music()`, `musicSync()`                                           |
+| `ERROR_PLAYLIST_NOT_FOUND`   | `playlist()`                                                       |
+| `ERROR_PLAYLIST_FETCH`       | `playlist()`                                                       |
+| `ERROR_ARTIST_NOT_FOUND`     | `artist()`                                                         |
+| `ERROR_ARTIST_FETCH`         | `artist()`                                                         |
+| `ERROR_MEDIA_NOT_FOUND`      | `mediaDetails()`                                                   |
+| `ERROR_MEDIA_FETCH`          | `mediaDetails()`                                                   |
+| `ERROR_SEARCH_FAILED`        | `searchMusic()`, `searchVideo()`, `searchList()`, `searchArtist()` |
+| `ERROR_SEARCH_FETCH`         | `searchMusic()`, `searchVideo()`, `searchList()`, `searchArtist()` |
+| `ERROR_STREAM_URL_NOT_FOUND` | `video()`, `music()`                                               |
+| `ERROR_STREAM_DOWNLOAD`      | `video()`, `videoSync()`, `music()`, `musicSync()`                 |
+
+## Notes
+
+* The root entry exports `Cookies` as a type only. To construct a cookie jar, import `Cookies` from `@khang07/zing-mp3-api/utils/cookies`.
+* The root entry exports the type name `SearhMedia` exactly as written in source.
+* `searchArtist()` is a public method, but its `SearchArtist` type is not re-exported from the root entry.
+* No test, example, or demo files were included in the provided source bundle.
+
+## License
+[MIT](https://github.com/GiaKhang1810/zing-mp3-api?tab=MIT-1-ov-file)