@kuriyona/cecilia 0.2.0 → 2.0.0-beta.1

package/README.md

@@ -1,6 +1,8 @@
 # Cecilia
 
-网易云音乐 API 的非官方 TypeScript 封装。
+网易云音乐 API 的非官方 TypeScript 封装。自行实现 weapi / eapi 加密与传输层（`node:crypto` + 全局 `fetch`），**不支持浏览器、Edge 等运行时，需要 Node ≥ 18**。
+
+可选地，通过 `@kuriyona/cecilia/elysia` 子路径可以把这 37 个函数起成一个 HTTP 服务（各一条 `GET` 路由）；该子路径需要额外安装 `elysia` + `@elysiajs/cors`，并**只能在 Bun 下监听**。
 
 ## 安装
 
@@ -11,59 +13,241 @@ pnpm add @kuriyona/cecilia
 ## 使用
 
 ```ts
-import { getPlaylistDetail, getLyric, getSongsDetail } from '@kuriyona/cecilia'
+import {
+  getArtist,
+  getPlaylistTracks,
+  getSongUrl,
+  search,
+} from '@kuriyona/cecilia'
 ```
 
-### `getPlaylistDetail(id)`
+所有函数返回**精简后的领域模型**（统一语义词表：`coverUrl`、`avatarUrl`、`creator`、`duration`（毫秒）等），可选项在原始响应缺失时不会出现。每个函数都接受末位可选的 `options`：
 
-获取歌单详情。
+```ts
+interface RequestOptions {
+  cookie?: string | Record<string, string> // 登录态，如浏览器复制的含 MUSIC_U 的 cookie
+  realIP?: string
+  timeout?: number // 默认 10000
+  ua?: string
+}
+```
 
 ```ts
-const detail = await getPlaylistDetail(123)
-// {
-//   id: 123,
-//   name: '歌单名',
-//   coverImgId: 456,
-//   coverImgUrl: 'https://example.com/cover.jpg',
-//   userId: 789,
-//   createTime: 1000000,
-//   songs: [{ id: 1, addTime: 2000000 }, ...]
-// }
+const artists = await search({ keywords: 'HoYo-MiX', type: 100 })
+const playlistId = artists.artists![0].id
+const tracks = await getPlaylistTracks({ id: playlistId, limit: 10 })
+const urls = await getSongUrl({ id: tracks.map((t) => t.id) })
 ```
 
-### `getLyric(id)`
+### 搜索
 
-获取歌词。
+```ts
+search(params) // keywords, type?, limit?, offset?
+cloudSearch(params)
+getSearchSuggest(params) // keywords?, mobile?
+getHotSearches()
+getHotSearchDetail()
+getDefaultSearchKeyword()
+searchMultimatch(params)
+```
+
+### 歌曲与歌词
 
 ```ts
-const lyric = await getLyric(1)
-// [
-//   { time: 1.5, text: 'Hello' },
-//   { time: 5, text: 'World' },
-// ]
+getSongsDetail(ids: number[])
+getSongUrl(params) // id, br?
+checkMusic(params) // id, br?
+getLyric(id)
+getLyricNew(id) // 含 wordLines 逐字歌词与 romaLines 罗马音
+getSimilarSongs(id)
 ```
 
-### `getSongsDetail(ids)`
+### 歌单
 
-批量获取歌曲详情。
+```ts
+getPlaylistDetail(id)
+getPlaylistTracks(params) // id, limit?, offset?
+getPlaylistDetailDynamic(id)
+getHighQualityTags()
+getTopPlaylists(params)
+getHighQualityPlaylists(params)
+getPlaylistCategories()
+getRelatedPlaylists(id)
+```
+
+### 歌手
+
+```ts
+getArtist(id)
+getArtistDetail(id)
+getArtistSongs(params)
+getArtistTopSongs(id)
+getArtistAlbums(params)
+getArtistList(params)
+getArtistDesc(id)
+getArtistMvs(params)
+getArtistVideos(params)
+```
+
+### 专辑
 
 ```ts
+getAlbum(id)
+getAlbumProduct(id)
+getAlbumDynamic(id)
+getAlbumSaleBoard(params)
+getAlbumPrivileges(id)
+getAlbumList(params)
+getNewestAlbums()
+```
+
+### 示例
+
+```ts
+const detail = await getPlaylistDetail(123)
+// {
+//   id: 123,
+//   name: '歌单名',
+//   creatorId: 789,
+//   coverUrl: 'https://example.com/cover.jpg',
+//   createTime: 1000000,
+//   songs: [{ id: 1, addTime: 2000000 }, ...] // 仅曲目 id，全量歌曲用 getPlaylistTracks
+// }
+
 const songs = await getSongsDetail([1, 2])
 // [
 //   {
 //     id: 1,
 //     name: 'Song A',
 //     artists: [{ id: 10, name: 'Artist 1' }],
-//     album: { id: 100, name: 'Album A', picUrl: '...' },
+//     album: { id: 100, name: 'Album A', coverUrl: '...' },
 //     duration: 200000,
 //   },
 // ]
 ```
 
+## 起一个 HTTP 服务器（可选，Bun）
+
+`@kuriyona/cecilia/elysia` 把 37 个函数各暴露成一条 `GET` 路由：既可以直接拿它返回的 Elysia 实例挂进自己的应用，也可以一键起服务。
+
+```bash
+pnpm add elysia @elysiajs/cors
+```
+
+```ts
+import { createApp, startServer } from '@kuriyona/cecilia/elysia'
+
+// 1) 只要现成的 Elysia 实例，自己 .use() / .listen() / 挂到别的实例上
+const app = createApp({ cors: { origin: ['http://localhost:5173'] } })
+
+// 2) 或者直接起服务：host/port 默认取 HOST / PORT 环境变量（缺省 127.0.0.1:3000）
+const { app, url } = startServer({
+  port: 3000,
+  cors: { origin: true },
+  auth: { token: process.env.TOKEN! }, // 要求 Authorization: Bearer <token>
+})
+console.log(`listening on ${url}`)
+// 关闭：app.stop()
+```
+
+仓库内自带可运行示例：
+
+```bash
+PORT=3000 TOKEN=demo bun run examples/elysia-server.ts
+```
+
+> `startServer` 依赖 Bun 的 `serve`，在 Node 下会**立即抛错**；`createApp()` 与 `app.handle()` 与运行时无关，也可以在 Node 里自备适配器使用。
+
+### 服务器选项
+
+| 字段 | 说明 |
+| --- | --- |
+| `host` | 监听地址，默认 `process.env.HOST ?? '127.0.0.1'` |
+| `port` | 监听端口，默认 `process.env.PORT ?? 3000`；`PORT` 非法直接抛错；`port: 0` 取随机端口（返回的 `url` 是实际地址） |
+| `cors` | 原样透传给 `@elysiajs/cors` 的 `CORSConfig`；不传则完全不启用 CORS |
+| `auth` | `{ token }`：所有路由都要求 `Authorization: Bearer <token>`（scheme 大小写不敏感、常量时间比较），失败返回 `401 { code: 401, message: 'Unauthorized' }` |
+
+- 入站 `Cookie` 头会**原样转发**给上游，客户端因此可以自带登录态（含 `MUSIC_U`）；服务端不保存任何 token。
+- 参数错误：id 列表不合法 → `422`；`type` / `order` / `albumType` 等枚举越界 → `400`；未知路径 → `404`。
+- 上游报错（`NeteaseApiError`）不拦截，走 Elysia 默认错误处理（`500`）。
+
+### 路由表
+
+| `GET` 路径 | query 参数 | 对应函数 |
+| --- | --- | --- |
+| `/search` | `keywords`（必填）、`type`、`limit`、`offset` | `search` |
+| `/cloudsearch` | 同上 | `cloudSearch` |
+| `/search/suggest` | `keywords`、`mobile` | `getSearchSuggest` |
+| `/search/hot` | — | `getHotSearches` |
+| `/search/hot/detail` | — | `getHotSearchDetail` |
+| `/search/default-keyword` | — | `getDefaultSearchKeyword` |
+| `/search/multimatch` | `keywords`、`type` | `searchMultimatch` |
+| `/song/detail` | `ids`（`1,2,3`） | `getSongsDetail` |
+| `/song/url` | `id`（`1,2`）、`br` | `getSongUrl` |
+| `/lyric` | `id` | `getLyric` |
+| `/lyric/new` | `id` | `getLyricNew` |
+| `/check/music` | `id`、`br` | `checkMusic` |
+| `/simi/song` | `id` | `getSimilarSongs` |
+| `/playlist/detail` | `id` | `getPlaylistDetail` |
+| `/playlist/track/all` | `id`、`limit`、`offset` | `getPlaylistTracks` |
+| `/playlist/detail/dynamic` | `id` | `getPlaylistDetailDynamic` |
+| `/playlist/highquality/tags` | — | `getHighQualityTags` |
+| `/playlist/top` | `cat`、`order`（`hot`/`new`）、`limit`、`offset` | `getTopPlaylists` |
+| `/playlist/highquality/list` | `cat`、`limit`、`before` | `getHighQualityPlaylists` |
+| `/playlist/catalogue` | — | `getPlaylistCategories` |
+| `/playlist/related` | `id` | `getRelatedPlaylists` |
+| `/artist` | `id` | `getArtist` |
+| `/artist/detail` | `id` | `getArtistDetail` |
+| `/artist/songs` | `id`、`order`（`hot`/`time`）、`limit`、`offset` | `getArtistSongs` |
+| `/artist/top/song` | `id` | `getArtistTopSongs` |
+| `/artist/album` | `id`、`limit`、`offset` | `getArtistAlbums` |
+| `/artist/list` | `area`、`type`、`initial`、`limit`、`offset` | `getArtistList` |
+| `/artist/desc` | `id` | `getArtistDesc` |
+| `/artist/mv` | `id`、`limit`、`offset` | `getArtistMvs` |
+| `/artist/video` | `id`、`size`、`cursor`、`order` | `getArtistVideos` |
+| `/album` | `id` | `getAlbum` |
+| `/album/product` | `id` | `getAlbumProduct` |
+| `/album/dynamic` | `id` | `getAlbumDynamic` |
+| `/album/sale/board` | `albumType`（`0`/`1`）、`type`（`daily`/`week`/`year`/`total`）、`year` | `getAlbumSaleBoard` |
+| `/album/privilege` | `id` | `getAlbumPrivileges` |
+| `/album/list` | `area`、`type`、`limit`、`offset` | `getAlbumList` |
+| `/album/new` | — | `getNewestAlbums` |
+
+```ts
+// 例：带上自己的登录 cookie 走一遍服务端
+const res = await fetch('http://127.0.0.1:3000/search?keywords=HoYo-MiX&type=100', {
+  headers: { cookie: 'MUSIC_U=...' },
+})
+const { artists } = (await res.json()) as SearchResult
+```
+
+## 从 0.2 升级
+
+`getPlaylistDetail` / `getLyric` / `getSongsDetail` 已改为走加密接口并对齐新词表（破坏性变更）：
+
+- `PlaylistDetails` → `PlaylistDetail`；`coverImgUrl` → `coverUrl`；`userId` → `creatorId`；删除 `coverImgId`
+- `getSongsDetail` 的 `album.picUrl` → `album.coverUrl`；`SongDetail` 现为 `Song` 的别名
+- `getLyric` 返回值不变
+
+## 已知限制
+
+- `/song/url`（eapi）免登录可用，但普通 cookie 只返回试听片段（`freeTrialInfo` 会给出截取起止时间），完整/高码率需要会员 cookie；`/song/url/v1`（xeapi）本期未实现。
+- **未实现匿名 token 与易盾反作弊 token（`checkToken` v2/v3）**，也不实现 xeapi。部分接口因此需要自行传入登录 cookie 才能调用。
+- `/simi/artist`（相似歌手）上游返回 `code 301 未登录`（weapi 与明文 api 均如此），本期未纳入导出。
+- `search({ type: 2000 })` 的语音搜索分支依赖上游当前响应结构（`songs` 或 `resources`），结构变化时会抛 `NeteaseApiError` 而不是返回空结果。
+- `getRelatedPlaylists` 抓取 `music.163.com/playlist?id=` 的 HTML；页面结构变化时会抛 `NeteaseApiError`。
+- 上游非 200 的成功码（如 `201`）默认视为失败；`request()` 的 `acceptCodes` 内部参数可按接口放行。
+- `@kuriyona/cecilia/elysia` 的 `startServer` 只在 **Bun** 下可用（Node 下抛错）；它不缓存响应、不存 token，也不会注入匿名 token，会员态仍需客户端自带 cookie。
+
 ## 开发
 
 ```bash
-pnpm test        # 运行测试
-pnpm test:watch  # 监听模式
-pnpm build       # 构建
-```
+pnpm test         # 离线测试（mock fetch + 加密自洽 + 响应整形）
+pnpm test:live    # 真实网络测试（含 test/probe.live.test.ts 探针，dump 到 docs/probe/）
+pnpm test:watch   # 监听模式
+pnpm build        # 构建（dist/{index,elysia}.{mjs,cjs,d.mts,d.cts}）
+pnpm clone:api-enhanced # 拉取 api-enhanced 参考实现（仅供比对，运行时不依赖）
+bun run examples/elysia-server.ts # 起 Elysia 示例服务器（需 Bun；PORT / TOKEN 可选）
+```
+
+离线测试直接断言各接口的请求 URL、加密方式与整形结果，不需要网络；`pnpm test:live -t probe` 会把上游原始响应写入 `docs/probe/<api>.json`（已 gitignore），用于核对字段路径。

package/dist/elysia.cjs

@@ -0,0 +1,288 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_src = require("./src-BoyQdkLi.cjs");
+let node_crypto = require("node:crypto");
+let _elysiajs_cors = require("@elysiajs/cors");
+let elysia = require("elysia");
+//#region src/elysia/routes.ts
+/** 入站 Cookie 原样转发给上游，会员态由调用方自带。 */
+const optionsOf = (request) => {
+	const cookie = request.headers.get("cookie");
+	return cookie === null ? void 0 : { cookie };
+};
+/** 逗号分隔的数字 id 列表，`1,2,3`。 */
+const idListSchema = elysia.t.String({ pattern: "^[0-9]+(,[0-9]+)*$" });
+const idsOf = (value) => value.split(",").map(Number);
+const pagingSchema = {
+	limit: elysia.t.Optional(elysia.t.Numeric()),
+	offset: elysia.t.Optional(elysia.t.Numeric())
+};
+/** 与 src/types/search.ts 的 SearchType 保持同步。 */
+const SEARCH_TYPES = [
+	1,
+	10,
+	100,
+	1e3,
+	1002,
+	1004,
+	1006,
+	1009,
+	1014,
+	2e3
+];
+const searchTypeOf = (value) => value === void 0 ? void 0 : SEARCH_TYPES.find((candidate) => candidate === value);
+/** 白名单外的取值返回 undefined，由调用方回 400。 */
+const pickEnum = (value, allowed) => value === void 0 ? void 0 : allowed.find((candidate) => candidate === value);
+const invalidEnum = (field, allowed) => ({
+	code: 400,
+	message: `${field} 只支持 ${allowed.join(" / ")}`
+});
+const TOP_PLAYLIST_ORDERS = ["hot", "new"];
+const ARTIST_SONG_ORDERS = ["hot", "time"];
+const ALBUM_SALE_TYPES = [
+	"daily",
+	"week",
+	"year",
+	"total"
+];
+const ALBUM_TYPES = ["0", "1"];
+/** Query 里 `albumType` 是字符串，窄化回 0 | 1。 */
+const albumTypeOf = (value) => value === void 0 ? void 0 : value === "0" ? 0 : 1;
+const searchRoutes = (app) => app.get("/search", ({ query, request, set }) => {
+	const type = searchTypeOf(query.type);
+	if (query.type !== void 0 && type === void 0) {
+		set.status = 400;
+		return invalidEnum("type", SEARCH_TYPES);
+	}
+	return require_src.search({
+		keywords: query.keywords,
+		type,
+		limit: query.limit,
+		offset: query.offset
+	}, optionsOf(request));
+}, { query: elysia.t.Object({
+	keywords: elysia.t.String({ minLength: 1 }),
+	type: elysia.t.Optional(elysia.t.Numeric()),
+	...pagingSchema
+}) }).get("/cloudsearch", ({ query, request, set }) => {
+	const type = searchTypeOf(query.type);
+	if (query.type !== void 0 && type === void 0) {
+		set.status = 400;
+		return invalidEnum("type", SEARCH_TYPES);
+	}
+	return require_src.cloudSearch({
+		keywords: query.keywords,
+		type,
+		limit: query.limit,
+		offset: query.offset
+	}, optionsOf(request));
+}, { query: elysia.t.Object({
+	keywords: elysia.t.String({ minLength: 1 }),
+	type: elysia.t.Optional(elysia.t.Numeric()),
+	...pagingSchema
+}) }).get("/search/suggest", ({ query, request }) => require_src.getSearchSuggest({
+	keywords: query.keywords,
+	mobile: query.mobile
+}, optionsOf(request)), { query: elysia.t.Object({
+	keywords: elysia.t.Optional(elysia.t.String()),
+	mobile: elysia.t.Optional(elysia.t.BooleanString())
+}) }).get("/search/hot", ({ request }) => require_src.getHotSearches(optionsOf(request))).get("/search/hot/detail", ({ request }) => require_src.getHotSearchDetail(optionsOf(request))).get("/search/default-keyword", ({ request }) => require_src.getDefaultSearchKeyword(optionsOf(request))).get("/search/multimatch", ({ query, request, set }) => {
+	const type = searchTypeOf(query.type);
+	if (query.type !== void 0 && type === void 0) {
+		set.status = 400;
+		return invalidEnum("type", SEARCH_TYPES);
+	}
+	return require_src.searchMultimatch({
+		keywords: query.keywords,
+		type
+	}, optionsOf(request));
+}, { query: elysia.t.Object({
+	keywords: elysia.t.Optional(elysia.t.String()),
+	type: elysia.t.Optional(elysia.t.Numeric())
+}) });
+const songRoutes = (app) => app.get("/song/detail", ({ query, request }) => require_src.getSongsDetail(idsOf(query.ids), optionsOf(request)), { query: elysia.t.Object({ ids: idListSchema }) }).get("/song/url", ({ query, request }) => require_src.getSongUrl({
+	id: idsOf(query.id),
+	br: query.br
+}, optionsOf(request)), { query: elysia.t.Object({
+	id: idListSchema,
+	br: elysia.t.Optional(elysia.t.Numeric())
+}) }).get("/lyric", ({ query, request }) => require_src.getLyric(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/lyric/new", ({ query, request }) => require_src.getLyricNew(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/check/music", ({ query, request }) => require_src.checkMusic({
+	id: query.id,
+	br: query.br
+}, optionsOf(request)), { query: elysia.t.Object({
+	id: elysia.t.Numeric(),
+	br: elysia.t.Optional(elysia.t.Numeric())
+}) }).get("/simi/song", ({ query, request }) => require_src.getSimilarSongs(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) });
+const playlistRoutes = (app) => app.get("/playlist/detail", ({ query, request }) => require_src.getPlaylistDetail(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/playlist/track/all", ({ query, request }) => require_src.getPlaylistTracks({
+	id: query.id,
+	limit: query.limit,
+	offset: query.offset
+}, optionsOf(request)), { query: elysia.t.Object({
+	id: elysia.t.Numeric(),
+	...pagingSchema
+}) }).get("/playlist/detail/dynamic", ({ query, request }) => require_src.getPlaylistDetailDynamic(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/playlist/highquality/tags", ({ request }) => require_src.getHighQualityTags(optionsOf(request))).get("/playlist/top", ({ query, request, set }) => {
+	const order = pickEnum(query.order, TOP_PLAYLIST_ORDERS);
+	if (query.order !== void 0 && order === void 0) {
+		set.status = 400;
+		return invalidEnum("order", TOP_PLAYLIST_ORDERS);
+	}
+	return require_src.getTopPlaylists({
+		cat: query.cat,
+		order,
+		limit: query.limit,
+		offset: query.offset
+	}, optionsOf(request));
+}, { query: elysia.t.Object({
+	cat: elysia.t.Optional(elysia.t.String()),
+	order: elysia.t.Optional(elysia.t.String()),
+	...pagingSchema
+}) }).get("/playlist/highquality/list", ({ query, request }) => require_src.getHighQualityPlaylists({
+	cat: query.cat,
+	limit: query.limit,
+	before: query.before
+}, optionsOf(request)), { query: elysia.t.Object({
+	cat: elysia.t.Optional(elysia.t.String()),
+	limit: elysia.t.Optional(elysia.t.Numeric()),
+	before: elysia.t.Optional(elysia.t.Numeric())
+}) }).get("/playlist/catalogue", ({ request }) => require_src.getPlaylistCategories(optionsOf(request))).get("/playlist/related", ({ query, request }) => require_src.getRelatedPlaylists(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) });
+const artistRoutes = (app) => app.get("/artist", ({ query, request }) => require_src.getArtist(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/artist/detail", ({ query, request }) => require_src.getArtistDetail(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/artist/songs", ({ query, request, set }) => {
+	const order = pickEnum(query.order, ARTIST_SONG_ORDERS);
+	if (query.order !== void 0 && order === void 0) {
+		set.status = 400;
+		return invalidEnum("order", ARTIST_SONG_ORDERS);
+	}
+	return require_src.getArtistSongs({
+		id: query.id,
+		order,
+		limit: query.limit,
+		offset: query.offset
+	}, optionsOf(request));
+}, { query: elysia.t.Object({
+	id: elysia.t.Numeric(),
+	order: elysia.t.Optional(elysia.t.String()),
+	...pagingSchema
+}) }).get("/artist/top/song", ({ query, request }) => require_src.getArtistTopSongs(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/artist/album", ({ query, request }) => require_src.getArtistAlbums({
+	id: query.id,
+	limit: query.limit,
+	offset: query.offset
+}, optionsOf(request)), { query: elysia.t.Object({
+	id: elysia.t.Numeric(),
+	...pagingSchema
+}) }).get("/artist/list", ({ query, request }) => require_src.getArtistList({
+	area: query.area,
+	type: query.type,
+	initial: query.initial,
+	limit: query.limit,
+	offset: query.offset
+}, optionsOf(request)), { query: elysia.t.Object({
+	area: elysia.t.Optional(elysia.t.Numeric()),
+	type: elysia.t.Optional(elysia.t.Numeric()),
+	initial: elysia.t.Optional(elysia.t.String()),
+	...pagingSchema
+}) }).get("/artist/desc", ({ query, request }) => require_src.getArtistDesc(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/artist/mv", ({ query, request }) => require_src.getArtistMvs({
+	id: query.id,
+	limit: query.limit,
+	offset: query.offset
+}, optionsOf(request)), { query: elysia.t.Object({
+	id: elysia.t.Numeric(),
+	...pagingSchema
+}) }).get("/artist/video", ({ query, request }) => require_src.getArtistVideos({
+	id: query.id,
+	size: query.size,
+	cursor: query.cursor,
+	order: query.order
+}, optionsOf(request)), { query: elysia.t.Object({
+	id: elysia.t.Numeric(),
+	size: elysia.t.Optional(elysia.t.Numeric()),
+	cursor: elysia.t.Optional(elysia.t.Numeric()),
+	order: elysia.t.Optional(elysia.t.Numeric())
+}) });
+const albumRoutes = (app) => app.get("/album", ({ query, request }) => require_src.getAlbum(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/album/product", ({ query, request }) => require_src.getAlbumProduct(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/album/dynamic", ({ query, request }) => require_src.getAlbumDynamic(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/album/sale/board", ({ query, request, set }) => {
+	const albumType = pickEnum(query.albumType, ALBUM_TYPES);
+	if (query.albumType !== void 0 && albumType === void 0) {
+		set.status = 400;
+		return invalidEnum("albumType", ALBUM_TYPES);
+	}
+	const type = pickEnum(query.type, ALBUM_SALE_TYPES);
+	if (query.type !== void 0 && type === void 0) {
+		set.status = 400;
+		return invalidEnum("type", ALBUM_SALE_TYPES);
+	}
+	return require_src.getAlbumSaleBoard({
+		albumType: albumTypeOf(albumType),
+		type,
+		year: query.year
+	}, optionsOf(request));
+}, { query: elysia.t.Object({
+	albumType: elysia.t.Optional(elysia.t.String()),
+	type: elysia.t.Optional(elysia.t.String()),
+	year: elysia.t.Optional(elysia.t.Numeric())
+}) }).get("/album/privilege", ({ query, request }) => require_src.getAlbumPrivileges(query.id, optionsOf(request)), { query: elysia.t.Object({ id: elysia.t.Numeric() }) }).get("/album/list", ({ query, request }) => require_src.getAlbumList({
+	area: query.area,
+	type: query.type,
+	limit: query.limit,
+	offset: query.offset
+}, optionsOf(request)), { query: elysia.t.Object({
+	area: elysia.t.Optional(elysia.t.String()),
+	type: elysia.t.Optional(elysia.t.String()),
+	...pagingSchema
+}) }).get("/album/new", ({ request }) => require_src.getNewestAlbums(optionsOf(request)));
+/** 37 个函数各一条 GET 路由，按 搜索 / 歌曲 / 歌单 / 歌手 / 专辑 依次注册。 */
+const registerRoutes = (app) => albumRoutes(artistRoutes(playlistRoutes(songRoutes(searchRoutes(app)))));
+//#endregion
+//#region src/elysia/app.ts
+/** scheme 大小写不敏感，比较用 timingSafeEqual（长度不等直接 false）。 */
+const isAuthorized = (request, token) => {
+	const header = request.headers.get("authorization");
+	if (header === null) return false;
+	const [scheme, value, ...rest] = header.split(" ");
+	if (rest.length > 0 || scheme?.toLowerCase() !== "bearer" || value === void 0) return false;
+	const expected = Buffer.from(token, "utf8");
+	const actual = Buffer.from(value, "utf8");
+	return expected.length === actual.length && (0, node_crypto.timingSafeEqual)(expected, actual);
+};
+/** 中间件风格插件：挂在实例上后，后续注册的路由都要先过鉴权。 */
+const withAuth = (options) => (app) => app.onBeforeHandle(({ request, set }) => {
+	if (isAuthorized(request, options.token)) return;
+	set.status = 401;
+	return {
+		code: 401,
+		message: "Unauthorized"
+	};
+});
+/**
+* 把 37 个 Cecilia 函数各注册成一条 GET 路由，返回可直接 `.use()` 或 `.listen()` 的 Elysia 实例。
+* CORS 先注册（预检早于鉴权短路），再鉴权，最后才是路由。
+*/
+const createApp = (options) => {
+	let app = new elysia.Elysia();
+	if (options?.cors !== void 0) app = app.use((0, _elysiajs_cors.cors)(options.cors));
+	if (options?.auth !== void 0) app = withAuth(options.auth)(app);
+	return registerRoutes(app);
+};
+//#endregion
+//#region src/elysia/server.ts
+const readPortEnv = () => {
+	const raw = process.env.PORT;
+	if (raw === void 0 || raw === "") return 3e3;
+	const port = Number(raw);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`PORT 环境变量非法: ${raw}`);
+	return port;
+};
+/** 同步返回：Bun 的 listen 是同步的，端口占用会同步抛出。 */
+const startServer = (options) => {
+	if (!("Bun" in globalThis)) throw new Error("@kuriyona/cecilia/elysia 的 startServer 需要 Bun 运行时（例如 bun run server.ts）；Node 下请用 createApp() 自备适配器。");
+	const port = options?.port ?? readPortEnv();
+	const host = options?.host ?? process.env.HOST ?? "127.0.0.1";
+	const app = createApp(options);
+	app.listen({
+		hostname: host,
+		port
+	});
+	return {
+		app,
+		url: app.server?.url.origin ?? `http://${host}:${port}`
+	};
+};
+//#endregion
+exports.createApp = createApp;
+exports.startServer = startServer;

package/dist/elysia.d.cts

@@ -0,0 +1,37 @@
+import { CORSConfig, CORSConfig as CORSConfig$1 } from "@elysiajs/cors";
+import { AnyElysia } from "elysia";
+
+//#region src/elysia/app.d.ts
+interface AuthOptions {
+  /** 静态 token；请求需带 `Authorization: Bearer <token>`。 */
+  token: string;
+}
+interface CeciliaAppOptions {
+  /** 透传给 @elysiajs/cors；不传则完全不启用 CORS。 */
+  cors?: CORSConfig$1;
+  /** 不传则全部路由公开。 */
+  auth?: AuthOptions;
+}
+/**
+ * 把 37 个 Cecilia 函数各注册成一条 GET 路由，返回可直接 `.use()` 或 `.listen()` 的 Elysia 实例。
+ * CORS 先注册（预检早于鉴权短路），再鉴权，最后才是路由。
+ */
+declare const createApp: (options?: CeciliaAppOptions) => AnyElysia;
+//#endregion
+//#region src/elysia/server.d.ts
+interface CeciliaServerOptions extends CeciliaAppOptions {
+  /** 默认 `process.env.HOST ?? "127.0.0.1"`。 */
+  host?: string;
+  /** 默认 `process.env.PORT ?? 3000`；非法 PORT 直接抛错。 */
+  port?: number;
+}
+interface CeciliaServer {
+  /** 关闭用 `app.stop()`。 */
+  app: AnyElysia;
+  /** 形如 `http://127.0.0.1:3000`（取自实际监听地址，`port: 0` 也可用）。 */
+  url: string;
+}
+/** 同步返回：Bun 的 listen 是同步的，端口占用会同步抛出。 */
+declare const startServer: (options?: CeciliaServerOptions) => CeciliaServer;
+//#endregion
+export { type AuthOptions, type CORSConfig, type CeciliaAppOptions, type CeciliaServer, type CeciliaServerOptions, createApp, startServer };

package/dist/elysia.d.mts

@@ -0,0 +1,37 @@
+import { CORSConfig, CORSConfig as CORSConfig$1 } from "@elysiajs/cors";
+import { AnyElysia } from "elysia";
+
+//#region src/elysia/app.d.ts
+interface AuthOptions {
+  /** 静态 token；请求需带 `Authorization: Bearer <token>`。 */
+  token: string;
+}
+interface CeciliaAppOptions {
+  /** 透传给 @elysiajs/cors；不传则完全不启用 CORS。 */
+  cors?: CORSConfig$1;
+  /** 不传则全部路由公开。 */
+  auth?: AuthOptions;
+}
+/**
+ * 把 37 个 Cecilia 函数各注册成一条 GET 路由，返回可直接 `.use()` 或 `.listen()` 的 Elysia 实例。
+ * CORS 先注册（预检早于鉴权短路），再鉴权，最后才是路由。
+ */
+declare const createApp: (options?: CeciliaAppOptions) => AnyElysia;
+//#endregion
+//#region src/elysia/server.d.ts
+interface CeciliaServerOptions extends CeciliaAppOptions {
+  /** 默认 `process.env.HOST ?? "127.0.0.1"`。 */
+  host?: string;
+  /** 默认 `process.env.PORT ?? 3000`；非法 PORT 直接抛错。 */
+  port?: number;
+}
+interface CeciliaServer {
+  /** 关闭用 `app.stop()`。 */
+  app: AnyElysia;
+  /** 形如 `http://127.0.0.1:3000`（取自实际监听地址，`port: 0` 也可用）。 */
+  url: string;
+}
+/** 同步返回：Bun 的 listen 是同步的，端口占用会同步抛出。 */
+declare const startServer: (options?: CeciliaServerOptions) => CeciliaServer;
+//#endregion
+export { type AuthOptions, type CORSConfig, type CeciliaAppOptions, type CeciliaServer, type CeciliaServerOptions, createApp, startServer };