@rexnow/libs 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Baran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# @rexnow/libs
+
+[![NPM Version](https://img.shields.io/npm/v/@rexnow/libs)](https://www.npmjs.com/package/@rexnow/libs)
+![NPM License](https://img.shields.io/npm/l/@rexnow/libs)
+
+> Rex Widget 开发工具库
+
+## 🚀 简介
+
+`@rexnow/libs` 是一个专为 Rex Widget 开发者设计的工具库，提供了完整的类型定义和测试工具，帮助开发者更高效地构建和测试 Widget 应用。
+
+## 📦 安装
+
+```bash
+npm install @rexnow/libs
+# 或
+yarn add @rexnow/libs
+# 或
+pnpm add @rexnow/libs
+```
+
+## 🛠️ 使用方法
+
+### 环境类型定义
+
+#### TypeScript 项目
+
+在你的项目中创建一个 `.d.ts` 文件，引入类型定义：
+
+```ts
+// rex-widget-env.d.ts
+/// <reference types="@rexnow/libs/env" />
+```
+
+这样你就可以在 TypeScript 代码中获得完整的类型支持：
+
+```ts
+// 现在可以使用 Widget 相关的类型和全局变量
+WidgetMetadata = {
+  name: "My Widget",
+  version: "1.0.0",
+  // ... 其他配置
+};
+
+async function loadDetail(url: string) {
+  const resp = await Widget.http.get('https://api.example.com/data')
+
+  const result: VideoItem = {
+    // ...
+  }
+  // ...
+  return result
+}
+```
+
+#### JavaScript 项目
+
+对于 JavaScript 项目，你可以使用 JSDoc 来获得类型提示：
+
+```js
+/**
+ * @type {import('@rexnow/libs/env')}
+ */
+
+
+WidgetMetadata = {
+  name: "My Widget",
+  version: "1.0.0",
+  // ... 其他配置
+};
+
+async function loadDetail(url) {
+  const resp = await Widget.http.get('https://api.example.com/data')
+  /**
+   * @type {import('@rexnow/libs/env').VideoItem}
+   */
+  const result = {
+    // ...
+  }
+  // ...
+  return result
+}
+```
+
+### 单元测试
+
+`@rexnow/libs` 提供了 `WidgetAdaptor` 来模拟 Widget 运行环境，方便进行单元测试。
+
+以 [Rstest](http://rstest.rs/) 为例：
+
+```ts
+import { expect, test, beforeAll } from "@rstest/core";
+
+beforeAll(async () => {
+  const { WidgetAdaptor } = await import("@rexnow/libs/widget-adaptor");
+  rstest.stubGlobal("Widget", WidgetAdaptor);
+});
+
+test("测试 HTTP 请求", async () => {
+  const response = await Widget.http.get("https://api.example.com/data");
+  expect(response).toBeDefined();
+  expect(response.status).toBe(200);
+});
+```
+
+#### TMDB
+
+如果需要使用到 `Widget.tmdb` 下的方法，需要环境变量中配置 `TMDB_API_KEY`
+
+```ini
+# .env
+TMDB_API_KEY=xxxx
+```
+
+```ts
+// rstest.config.ts
+
+import { defineConfig } from "@rstest/core";
+
+export default defineConfig({
+  testEnvironment: "node",
+  pool: {
+    type: "forks",
+    execArgv: ["--env-file=.env"], // 通过指定 env-file 加载环境变量
+  },
+});
+```
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request 来改善这个项目。
+
+## 📄 许可证
+
+MIT License

package/dist/env/common.d.ts

@@ -0,0 +1,55 @@
+interface BaseParams {
+    id: string;
+    /**
+     * TMDB ID
+     */
+    tmdbId?: string;
+    /**
+     * IMDB ID
+     */
+    imdbId?: string;
+    /**
+     * 类型
+     */
+    type: 'tv' | 'movie';
+    /**
+     * 搜索关键词
+     */
+    title: string;
+    /**
+     * 剧名
+     */
+    seriesName?: string;
+    /**
+     * 集名
+     */
+    episodeName?: string;
+    /**
+     * 播出日期
+     */
+    airDate?: string;
+    /**
+     * 首播日期
+     */
+    premiereDate?: string;
+    /**
+     * 时长
+     */
+    runtime?: string;
+    /**
+     * 季
+     */
+    season?: string;
+    /**
+     * 集
+     */
+    episode?: string;
+    /**
+     * 链接
+     */
+    link?: string;
+    /**
+     * 视频链接
+     */
+    videoUrl?: string;
+}

package/dist/env/danmu.d.ts

@@ -0,0 +1,36 @@
+interface AnimeItem {
+    animeId: string | number;
+    animeTitle: string;
+    bangumiId?: string | number;
+}
+interface GetDetailResponseItem {
+    /**
+     * 透传给 getComments 的 commentId
+     */
+    episodeId: string | number;
+    episodeTitle: string;
+}
+interface EpisodeItem {
+    commentId: string;
+}
+interface CommentItem {
+    cid?: number | string;
+    p: `${number},${1 | 4 | 5},${number},${string}`;
+    m: string;
+}
+/**
+ * README 弹幕格式 2：[时间, 位置, 颜色, 额外信息, 文本]
+ */
+type CommentTuple = [number, string, string, string, string];
+interface GetCommentsResponse {
+    count: number;
+    comments: Array<CommentItem | CommentTuple>;
+}
+interface GetDanmuWithSegmentTimeParams extends BaseParams, AnimeItem, EpisodeItem {
+    /**
+     * 分段时间
+     */
+    segmentTime: number;
+}
+interface GetDanmuWithSegmentTimeResponse extends GetCommentsResponse {
+}

package/dist/env/index.d.ts

@@ -0,0 +1,7 @@
+import './common.js';
+import './danmu.js';
+import './metadata.js';
+import './stream.js';
+import './subtitle.js';
+import './video.js';
+import './widget.js';

package/dist/env/metadata.d.ts

@@ -0,0 +1,119 @@
+declare let WidgetMetadata: WidgetMetadata;
+interface WidgetMetadata {
+    /** Widget 唯一标识符 */
+    id: string;
+    /** Widget 显示标题 */
+    title: string;
+    /** Widget 描述 */
+    description?: string;
+    /** 作者 */
+    author?: string;
+    /** 网站地址 */
+    site?: string;
+    /** Widget 版本 */
+    version?: string;
+    /** 所需 Rex 版本 */
+    requiredVersion?: string;
+    /**
+     * Widget 图标地址（官方 demo 字段名）
+     */
+    icon?: string;
+    /**
+     * Widget 图标地址（Rex 插件字段名，与 icon 同一含义）
+     */
+    iconurl?: string;
+    /**
+     * 文案国际化：locale → 源文案 → 译文
+     */
+    i18n?: Partial<Record<WidgetI18nLocale, Record<string, string>>>;
+    /**
+     * 详情数据缓存时长，单位：秒
+     * @default 60
+     */
+    detailCacheDuration?: number;
+    /**
+     * 全局参数配置
+     */
+    globalParams?: WidgetModuleParam[];
+    /** 功能模块列表 */
+    modules: WidgetModule[];
+    /** 搜索功能配置 */
+    search?: {
+        /** 搜索标题 */
+        title: string;
+        /** 搜索函数名 */
+        functionName: string;
+        /** 搜索参数配置 */
+        params: WidgetModuleParam[];
+    };
+}
+interface BaseWidgetModule {
+    /** 模块唯一标识符 */
+    id: string;
+    /** 模块类型 */
+    type?: 'danmu' | 'stream' | 'subtitle';
+    /** 模块标题 */
+    title: string;
+    /** 模块描述 */
+    description?: string;
+    /** 是否需要 WebView */
+    requiresWebView?: boolean;
+    /** 处理函数名 */
+    functionName: string;
+    /** 是否支持分段模式 */
+    sectionMode?: boolean;
+    /**
+     * 缓存时长，单位：秒
+     * @default 3600
+     */
+    cacheDuration?: number;
+    /** 参数配置 */
+    params?: WidgetModuleParam[];
+}
+interface WidgetModuleVideo extends BaseWidgetModule {
+    type?: never;
+}
+interface WidgetModuleDanmu extends BaseWidgetModule {
+    type: 'danmu';
+    id: 'searchDanmu' | 'getDetail' | 'getComments' | 'getDanmuWithSegmentTime';
+}
+interface WidgetModuleStream extends BaseWidgetModule {
+    type: 'stream';
+    id: 'loadResource';
+}
+interface WidgetModuleSubtitle extends BaseWidgetModule {
+    type: 'subtitle';
+    id: 'loadSubtitle';
+}
+type WidgetI18nLocale = 'en' | 'zh-Hans' | 'zh-Hant' | 'ja' | 'ko' | 'es' | 'fr' | 'pt-BR' | 'ru' | 'ar' | (string & {});
+type WidgetModule = WidgetModuleVideo | WidgetModuleDanmu | WidgetModuleStream | WidgetModuleSubtitle;
+type WidgetModuleParamType = 'input' | 'constant' | 'enumeration' | 'count' | 'page' | 'offset' | 'language' | 'userId';
+interface WidgetModuleParam {
+    /** 参数名 */
+    name: string;
+    /** 参数显示标题 */
+    title: string;
+    /** 参数类型 */
+    type: WidgetModuleParamType;
+    /** 参数描述 */
+    description?: string;
+    /** 默认值 */
+    value?: string;
+    /** 当符合该条件时才会触发该参数 */
+    belongTo?: {
+        /** 所属参数的子参数 */
+        paramName: string;
+        /** 所属参数包含的值 */
+        value: string[];
+    };
+    /** 占位符选项 */
+    placeholders?: Array<{
+        title: string;
+        value: string;
+    }>;
+    /** 枚举选项 */
+    enumOptions?: Array<{
+        title: string;
+        value: string;
+    }>;
+}

package/dist/env/stream.d.ts

@@ -0,0 +1,8 @@
+interface StreamSourceItem {
+    name: string;
+    description?: string;
+    url: string;
+    customHeaders?: Record<string, string>;
+    headers?: Record<string, string>;
+    playerType?: 'system' | 'app';
+}

package/dist/env/subtitle.d.ts

@@ -0,0 +1,34 @@
+interface SubtitleItem {
+    id: string;
+    title: string;
+    lang: string;
+    count: number;
+    url: string;
+}
+interface SubtitleArchiveFile {
+    /** 解压目录内的相对路径，原样返回，不要拼绝对路径 */
+    path: string;
+    /** 文件名 */
+    name: string;
+    /** 小写扩展名 */
+    extension: string;
+    /** 文件大小，可能为空 */
+    size?: number;
+}
+interface ResolveSubtitleArchiveParams {
+    archiveName?: string;
+    archiveUrl?: string;
+    subtitleId?: string;
+    subtitleName?: string;
+    subtitleLanguage?: string;
+    /** 全部解压文件的 JSON 字符串 */
+    files?: string;
+    /** 客户端支持的字幕文件 JSON 字符串 */
+    subtitleFiles?: string;
+}
+type ResolveSubtitleArchiveResult = string | string[] | {
+    path: string;
+} | {
+    files: string[];
+} | null;
+declare let resolveSubtitleArchive: (params: ResolveSubtitleArchiveParams) => ResolveSubtitleArchiveResult | Promise<ResolveSubtitleArchiveResult>;

package/dist/env/video.d.ts

@@ -0,0 +1,91 @@
+interface GenreItem {
+    /** 分类 ID，详情页打开列表时作为 genreId 回传 */
+    id: string;
+    /** 分类标题 */
+    title: string;
+}
+interface PersonItem {
+    /** 人物 ID，详情页打开列表时作为 peopleId 回传 */
+    id: string;
+    /** 人物名称 */
+    title: string;
+    /** 头像地址 */
+    avatar?: string;
+    /** 角色 */
+    role?: string;
+}
+interface TrailerItem {
+    /** 预告片封面 */
+    coverUrl?: string;
+    /** 预告片地址 */
+    url: string;
+}
+interface VideoItemChild {
+    /** 唯一标识符。对于 url 类型为 url 地址,对于 douban/imdb/tmdb 类型为对应 ID。tmdb ID 格式为 type.id,如 tv.123 */
+    id: string;
+    /** 类型标识。forward 表示可匹配的网盘资源身份，客户端会归一为 fw- 前缀 */
+    type: 'url' | 'detail' | 'douban' | 'imdb' | 'tmdb' | 'forward';
+    /** 标题 */
+    title: string;
+    /** 通用兜底封面。横图位排在 backdropPath 之后，竖图位排在最后 */
+    coverUrl?: string;
+    /** 纵向封面图片地址 */
+    posterPath?: string;
+    /** 详情页海报位专用，覆盖 posterPath */
+    detailPoster?: string;
+    /** 横向封面地址 */
+    backdropPath?: string;
+    /** 发布时间 */
+    releaseDate?: string;
+    /** 媒体类型 */
+    mediaType?: 'tv' | 'movie';
+    /** 评分 */
+    rating?: string;
+    /** 分类 */
+    genreTitle?: string;
+    /** 可点击分类，详情页会用 id 打开列表 */
+    genreItems?: GenreItem[];
+    /** 演员/人物，详情页会用 id 打开列表 */
+    peoples?: PersonItem[];
+    /** 时长(秒) */
+    duration?: number;
+    /** 时长文本格式 */
+    durationText?: string;
+    /** 预览视频地址 */
+    previewUrl?: string;
+    /** 预告片 */
+    trailers?: TrailerItem[];
+    /** 视频播放地址 */
+    videoUrl?: string;
+    /** 详情页地址 */
+    link: string;
+    /** 集数 */
+    episode?: number;
+    /** 描述 */
+    description?: string;
+    /** 播放器类型 */
+    playerType?: 'system' | 'app';
+    /** 剧照/截图列表，详情页展示 */
+    backdropPaths?: string[];
+}
+/**
+ * 视频项目的元数据接口
+ */
+interface VideoItem extends VideoItemChild {
+    /** 子项目列表(最多一层) */
+    childItems?: VideoItemChild[];
+    /** 剧集列表 */
+    episodeItems?: VideoItem[];
+    /** 相关推荐 */
+    relatedItems?: VideoItem[];
+}
+/**
+ * 列表模块隐式参数。从详情页分类或人物进入列表时由客户端注入。
+ */
+interface VideoListParams {
+    /** 分类 ID，对应 genreItems[].id */
+    genreId?: string;
+    /** 人物 ID，对应 peoples[].id */
+    peopleId?: string;
+}
+declare let loadDetail: (link: string) => Promise<VideoItem | VideoItem[] | null>;

package/dist/env/widget.d.ts

@@ -0,0 +1 @@
+declare const Widget: typeof import('../widget-adaptor.js').WidgetAdaptor;

package/dist/env.js

@@ -0,0 +1 @@
+export { };

package/dist/env.zod/index.ts

@@ -0,0 +1,371 @@
+// Generated by ts-to-zod
+import { z } from "zod";
+
+export const baseParamsSchema = z.object({
+    id: z.string(),
+    /**
+     * TMDB ID
+     */
+    tmdbId: z.string().optional(),
+    /**
+     * IMDB ID
+     */
+    imdbId: z.string().optional(),
+    /**
+     * 类型
+     */
+    type: z.union([z.literal("tv"), z.literal("movie")]),
+    /**
+     * 搜索关键词
+     */
+    title: z.string(),
+    /**
+     * 剧名
+     */
+    seriesName: z.string().optional(),
+    /**
+     * 集名
+     */
+    episodeName: z.string().optional(),
+    /**
+     * 播出日期
+     */
+    airDate: z.string().optional(),
+    /**
+     * 首播日期
+     */
+    premiereDate: z.string().optional(),
+    /**
+     * 时长
+     */
+    runtime: z.string().optional(),
+    /**
+     * 季
+     */
+    season: z.string().optional(),
+    /**
+     * 集
+     */
+    episode: z.string().optional(),
+    /**
+     * 链接
+     */
+    link: z.string().optional(),
+    /**
+     * 视频链接
+     */
+    videoUrl: z.string().optional()
+});
+
+export const animeItemSchema = z.object({
+    animeId: z.union([z.string(), z.number()]),
+    animeTitle: z.string(),
+    bangumiId: z.union([z.string(), z.number()]).optional()
+});
+
+export const getDetailResponseItemSchema = z.object({
+    /**
+     * 透传给 getComments 的 commentId
+     */
+    episodeId: z.union([z.string(), z.number()]),
+    episodeTitle: z.string()
+});
+
+export const episodeItemSchema = z.object({
+    commentId: z.string()
+});
+
+export const commentItemSchema = z.object({
+    cid: z.union([z.number(), z.string()]).optional(),
+    p: z.string(),
+    m: z.string()
+});
+
+/**
+ * README 弹幕格式 2：[时间, 位置, 颜色, 额外信息, 文本]
+ */
+export const commentTupleSchema = z.tuple([z.number(), z.string(), z.string(), z.string(), z.string()]);
+
+export const getCommentsResponseSchema = z.object({
+    count: z.number(),
+    comments: z.array(z.union([commentItemSchema, commentTupleSchema]))
+});
+
+export const getDanmuWithSegmentTimeParamsSchema = baseParamsSchema.extend(animeItemSchema.shape).extend(episodeItemSchema.shape).extend({
+    /**
+     * 分段时间
+     */
+    segmentTime: z.number()
+});
+
+export const getDanmuWithSegmentTimeResponseSchema = getCommentsResponseSchema;
+
+export const widgetI18nLocaleSchema = z.union([z.literal("en"), z.literal("zh-Hans"), z.literal("zh-Hant"), z.literal("ja"), z.literal("ko"), z.literal("es"), z.literal("fr"), z.literal("pt-BR"), z.literal("ru"), z.literal("ar"), z.string()]);
+
+export const widgetModuleParamTypeSchema = z.union([z.literal("input"), z.literal("constant"), z.literal("enumeration"), z.literal("count"), z.literal("page"), z.literal("offset"), z.literal("language"), z.literal("userId")]);
+
+export const widgetModuleParamSchema = z.object({
+    /** 参数名 */
+    name: z.string(),
+    /** 参数显示标题 */
+    title: z.string(),
+    /** 参数类型 */
+    type: widgetModuleParamTypeSchema,
+    /** 参数描述 */
+    description: z.string().optional(),
+    /** 默认值 */
+    value: z.string().optional(),
+    /** 当符合该条件时才会触发该参数 */
+    belongTo: z.object({
+        /** 所属参数的子参数 */
+        paramName: z.string(),
+        /** 所属参数包含的值 */
+        value: z.array(z.string())
+    }).optional(),
+    /** 占位符选项 */
+    placeholders: z.array(z.object({
+        title: z.string(),
+        value: z.string()
+    })).optional(),
+    /** 枚举选项 */
+    enumOptions: z.array(z.object({
+        title: z.string(),
+        value: z.string()
+    })).optional()
+});
+
+export const streamSourceItemSchema = z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    url: z.string(),
+    customHeaders: z.record(z.string(), z.string()).optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    playerType: z.union([z.literal("system"), z.literal("app")]).optional()
+});
+
+export const subtitleItemSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    lang: z.string(),
+    count: z.number(),
+    url: z.string()
+});
+
+export const subtitleArchiveFileSchema = z.object({
+    /** 解压目录内的相对路径，原样返回，不要拼绝对路径 */
+    path: z.string(),
+    /** 文件名 */
+    name: z.string(),
+    /** 小写扩展名 */
+    extension: z.string(),
+    /** 文件大小，可能为空 */
+    size: z.number().optional()
+});
+
+export const resolveSubtitleArchiveParamsSchema = z.object({
+    archiveName: z.string().optional(),
+    archiveUrl: z.string().optional(),
+    subtitleId: z.string().optional(),
+    subtitleName: z.string().optional(),
+    subtitleLanguage: z.string().optional(),
+    /** 全部解压文件的 JSON 字符串 */
+    files: z.string().optional(),
+    /** 客户端支持的字幕文件 JSON 字符串 */
+    subtitleFiles: z.string().optional()
+});
+
+export const resolveSubtitleArchiveResultSchema = z.union([z.string(), z.array(z.string()), z.object({
+        path: z.string()
+    }), z.object({
+        files: z.array(z.string())
+    })]).nullable();
+
+export const genreItemSchema = z.object({
+    /** 分类 ID，详情页打开列表时作为 genreId 回传 */
+    id: z.string(),
+    /** 分类标题 */
+    title: z.string()
+});
+
+export const personItemSchema = z.object({
+    /** 人物 ID，详情页打开列表时作为 peopleId 回传 */
+    id: z.string(),
+    /** 人物名称 */
+    title: z.string(),
+    /** 头像地址 */
+    avatar: z.string().optional(),
+    /** 角色 */
+    role: z.string().optional()
+});
+
+export const trailerItemSchema = z.object({
+    /** 预告片封面 */
+    coverUrl: z.string().optional(),
+    /** 预告片地址 */
+    url: z.string()
+});
+
+export const videoItemChildSchema = z.object({
+    /** 唯一标识符。对于 url 类型为 url 地址,对于 douban/imdb/tmdb 类型为对应 ID。tmdb ID 格式为 type.id,如 tv.123 */
+    id: z.string(),
+    /** 类型标识。forward 表示可匹配的网盘资源身份，客户端会归一为 fw- 前缀 */
+    type: z.union([z.literal("url"), z.literal("detail"), z.literal("douban"), z.literal("imdb"), z.literal("tmdb"), z.literal("forward")]),
+    /** 标题 */
+    title: z.string(),
+    /** 通用兜底封面。横图位排在 backdropPath 之后，竖图位排在最后 */
+    coverUrl: z.string().optional(),
+    /** 纵向封面图片地址 */
+    posterPath: z.string().optional(),
+    /** 详情页海报位专用，覆盖 posterPath */
+    detailPoster: z.string().optional(),
+    /** 横向封面地址 */
+    backdropPath: z.string().optional(),
+    /** 发布时间 */
+    releaseDate: z.string().optional(),
+    /** 媒体类型 */
+    mediaType: z.union([z.literal("tv"), z.literal("movie")]).optional(),
+    /** 评分 */
+    rating: z.string().optional(),
+    /** 分类 */
+    genreTitle: z.string().optional(),
+    /** 可点击分类，详情页会用 id 打开列表 */
+    genreItems: z.array(genreItemSchema).optional(),
+    /** 演员/人物，详情页会用 id 打开列表 */
+    peoples: z.array(personItemSchema).optional(),
+    /** 时长(秒) */
+    duration: z.number().optional(),
+    /** 时长文本格式 */
+    durationText: z.string().optional(),
+    /** 预览视频地址 */
+    previewUrl: z.string().optional(),
+    /** 预告片 */
+    trailers: z.array(trailerItemSchema).optional(),
+    /** 视频播放地址 */
+    videoUrl: z.string().optional(),
+    /** 详情页地址 */
+    link: z.string(),
+    /** 集数 */
+    episode: z.number().optional(),
+    /** 描述 */
+    description: z.string().optional(),
+    /** 播放器类型 */
+    playerType: z.union([z.literal("system"), z.literal("app")]).optional(),
+    /** 剧照/截图列表，详情页展示 */
+    backdropPaths: z.array(z.string()).optional()
+});
+
+/**
+ * 视频项目的元数据接口
+ */
+export const videoItemSchema: z.ZodTypeAny = z.lazy((): z.ZodTypeAny => videoItemChildSchema.extend({
+    /** 子项目列表(最多一层) */
+    childItems: z.array(videoItemChildSchema).optional(),
+    /** 剧集列表 */
+    episodeItems: z.array(videoItemSchema).optional(),
+    /** 相关推荐 */
+    relatedItems: z.array(videoItemSchema).optional()
+}));
+
+/**
+ * 列表模块隐式参数。从详情页分类或人物进入列表时由客户端注入。
+ */
+export const videoListParamsSchema = z.object({
+    /** 分类 ID，对应 genreItems[].id */
+    genreId: z.string().optional(),
+    /** 人物 ID，对应 peoples[].id */
+    peopleId: z.string().optional()
+});
+
+export const baseWidgetModuleSchema = z.object({
+    /** 模块唯一标识符 */
+    id: z.string(),
+    /** 模块类型 */
+    type: z.union([z.literal("danmu"), z.literal("stream"), z.literal("subtitle")]).optional(),
+    /** 模块标题 */
+    title: z.string(),
+    /** 模块描述 */
+    description: z.string().optional(),
+    /** 是否需要 WebView */
+    requiresWebView: z.boolean().optional(),
+    /** 处理函数名 */
+    functionName: z.string(),
+    /** 是否支持分段模式 */
+    sectionMode: z.boolean().optional(),
+    /**
+     * 缓存时长，单位：秒
+     * @default 3600
+     */
+    cacheDuration: z.number().optional().default(3600),
+    /** 参数配置 */
+    params: z.array(widgetModuleParamSchema).optional()
+});
+
+export const widgetModuleVideoSchema = baseWidgetModuleSchema.extend({
+    type: z.never().optional()
+});
+
+export const widgetModuleDanmuSchema = baseWidgetModuleSchema.extend({
+    type: z.literal("danmu"),
+    id: z.union([z.literal("searchDanmu"), z.literal("getDetail"), z.literal("getComments"), z.literal("getDanmuWithSegmentTime")])
+});
+
+export const widgetModuleStreamSchema = baseWidgetModuleSchema.extend({
+    type: z.literal("stream"),
+    id: z.literal("loadResource")
+});
+
+export const widgetModuleSubtitleSchema = baseWidgetModuleSchema.extend({
+    type: z.literal("subtitle"),
+    id: z.literal("loadSubtitle")
+});
+
+export const widgetModuleSchema = z.union([widgetModuleVideoSchema, widgetModuleDanmuSchema, widgetModuleStreamSchema, widgetModuleSubtitleSchema]);
+
+export const widgetMetadataSchema = z.object({
+    /** Widget 唯一标识符 */
+    id: z.string(),
+    /** Widget 显示标题 */
+    title: z.string(),
+    /** Widget 描述 */
+    description: z.string().optional(),
+    /** 作者 */
+    author: z.string().optional(),
+    /** 网站地址 */
+    site: z.string().optional(),
+    /** Widget 版本 */
+    version: z.string().optional(),
+    /** 所需 Rex 版本 */
+    requiredVersion: z.string().optional(),
+    /**
+     * Widget 图标地址（官方 demo 字段名）
+     */
+    icon: z.string().optional(),
+    /**
+     * Widget 图标地址（Rex 插件字段名，与 icon 同一含义）
+     */
+    iconurl: z.string().optional(),
+    /**
+     * 文案国际化：locale → 源文案 → 译文
+     */
+    i18n: z.record(widgetI18nLocaleSchema, z.record(z.string(), z.string())).optional(),
+    /**
+     * 详情数据缓存时长，单位：秒
+     * @default 60
+     */
+    detailCacheDuration: z.number().optional().default(60),
+    /**
+     * 全局参数配置
+     */
+    globalParams: z.array(widgetModuleParamSchema).optional(),
+    /** 功能模块列表 */
+    modules: z.array(widgetModuleSchema),
+    /** 搜索功能配置 */
+    search: z.object({
+        /** 搜索标题 */
+        title: z.string(),
+        /** 搜索函数名 */
+        functionName: z.string(),
+        /** 搜索参数配置 */
+        params: z.array(widgetModuleParamSchema)
+    }).optional()
+});

package/dist/widget-adaptor.d.ts

@@ -0,0 +1,51 @@
+interface RequestOptions {
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    zlibMode?: boolean;
+    base64Data?: boolean;
+    allow_redirects?: boolean;
+}
+interface HttpRequestOptions extends RequestOptions {
+    url: string;
+    method?: 'GET' | 'POST';
+    data?: unknown;
+    body?: unknown;
+}
+export declare const WidgetAdaptor: {
+    http: {
+        get: <T>(url: string, options?: RequestOptions) => Promise<{
+            data: T;
+            statusCode: number;
+            headers: Record<string, string>;
+        }>;
+        post: <T>(url: string, body: unknown, options?: RequestOptions) => Promise<{
+            data: T;
+            statusCode: number;
+            headers: Record<string, string>;
+        }>;
+        request: <T>(options: HttpRequestOptions) => Promise<{
+            data: T;
+            statusCode: number;
+            headers: Record<string, string>;
+        }>;
+    };
+    tmdb: {
+        get: <T>(url: string, options?: RequestOptions) => Promise<T>;
+    };
+    html: {
+        load: (...args: Parameters<typeof import('cheerio').load>) => Promise<ReturnType<typeof import('cheerio').load>>;
+    };
+    storage: {
+        get: (key: string) => Promise<string | null>;
+        set: (key: string, value: string) => Promise<void>;
+        remove: (key: string) => Promise<void>;
+        keys: () => Promise<string[]>;
+        clear: () => Promise<void>;
+    };
+    sharedCache: {
+        get: (namespace: string, key: string) => unknown;
+        set: (namespace: string, key: string, value?: unknown) => void;
+        remove: (namespace: string, key: string) => void;
+    };
+};
+export {};

package/dist/widget-adaptor.js

@@ -0,0 +1,135 @@
+import node_fs from "node:fs";
+import node_os from "node:os";
+import node_path from "node:path";
+import { promisify } from "node:util";
+import { inflate } from "node:zlib";
+import { load } from "cheerio";
+const createHttpRequest = async (url, method, options)=>{
+    const fetchOptions = {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            ...options?.headers
+        }
+    };
+    if ('POST' === method && options?.body !== void 0) fetchOptions.body = 'string' == typeof options.body ? options.body : JSON.stringify(options.body);
+    const uri = new URL(url);
+    if (options?.params) Object.entries(options.params).forEach(([key, value])=>{
+        uri.searchParams.set(key, value);
+    });
+    let data;
+    const response = await fetch(uri, fetchOptions);
+    if (options?.base64Data) {
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        const base64Data = buffer.toString('base64');
+        data = base64Data;
+    } else if (options?.zlibMode) data = (await promisify(inflate)(await response.arrayBuffer())).toString('utf-8');
+    else {
+        const textData = await response.text();
+        try {
+            data = JSON.parse(textData);
+        } catch  {
+            data = textData;
+        }
+    }
+    const headers = {};
+    response.headers.forEach((value, key)=>{
+        if (headers[key]) headers[key] = `${headers[key]}, ${value}`;
+        else headers[key] = value;
+    });
+    return {
+        data,
+        statusCode: response.status,
+        headers
+    };
+};
+const ADAPTOR_ROOT = node_path.join(node_os.tmpdir(), 'rex-widget-adaptor');
+const STORAGE_CONFIG = {
+    get DIR () {
+        const dir = node_path.join(ADAPTOR_ROOT, 'storage');
+        if (!node_fs.existsSync(dir)) node_fs.mkdirSync(dir, {
+            recursive: true
+        });
+        return dir;
+    },
+    getFilePath: (key)=>node_path.join(STORAGE_CONFIG.DIR, encodeURIComponent(key))
+};
+const SHARED_CACHE_CONFIG = {
+    getFilePath: (namespace, key)=>{
+        const dir = node_path.join(ADAPTOR_ROOT, 'shared-cache', encodeURIComponent(namespace));
+        if (!node_fs.existsSync(dir)) node_fs.mkdirSync(dir, {
+            recursive: true
+        });
+        return node_path.join(dir, encodeURIComponent(key));
+    }
+};
+const WidgetAdaptor = {
+    http: {
+        get: async (url, options)=>createHttpRequest(url, 'GET', options),
+        post: async (url, body, options)=>createHttpRequest(url, 'POST', {
+                ...options,
+                body
+            }),
+        request: async (options)=>{
+            const { url, method = 'GET', data, body, ...rest } = options;
+            return createHttpRequest(url, method, {
+                ...rest,
+                body: body ?? data
+            });
+        }
+    },
+    tmdb: {
+        get: async (url, options)=>{
+            const urlObj = new URL(`/3/${url}`, 'https://api.themoviedb.org/');
+            options ||= {};
+            options.headers = {
+                ...options.headers,
+                accept: 'application/json',
+                Authorization: `Bearer ${process.env.TMDB_API_KEY}`
+            };
+            const resp = await WidgetAdaptor.http.get(urlObj.toString(), options);
+            return resp.data;
+        }
+    },
+    html: {
+        load: (...args)=>new Promise((resolve)=>resolve(load(...args)))
+    },
+    storage: {
+        get: async (key)=>{
+            const filePath = STORAGE_CONFIG.getFilePath(key);
+            if (!node_fs.existsSync(filePath)) return null;
+            return node_fs.promises.readFile(filePath, 'utf-8');
+        },
+        set: (key, value)=>node_fs.promises.writeFile(STORAGE_CONFIG.getFilePath(key), value, 'utf-8'),
+        remove: (key)=>node_fs.promises.rm(STORAGE_CONFIG.getFilePath(key)),
+        keys: async ()=>{
+            const keys = await node_fs.promises.readdir(STORAGE_CONFIG.DIR);
+            return keys.map((key)=>decodeURIComponent(key));
+        },
+        clear: ()=>node_fs.promises.rm(STORAGE_CONFIG.DIR, {
+                recursive: true
+            })
+    },
+    sharedCache: {
+        get: (namespace, key)=>{
+            const filePath = SHARED_CACHE_CONFIG.getFilePath(namespace, key);
+            if (!node_fs.existsSync(filePath)) return null;
+            const raw = node_fs.readFileSync(filePath, 'utf-8');
+            try {
+                return JSON.parse(raw);
+            } catch  {
+                return raw;
+            }
+        },
+        set: (namespace, key, value)=>{
+            node_fs.writeFileSync(SHARED_CACHE_CONFIG.getFilePath(namespace, key), JSON.stringify(value ?? null), 'utf-8');
+        },
+        remove: (namespace, key)=>{
+            node_fs.rmSync(SHARED_CACHE_CONFIG.getFilePath(namespace, key), {
+                force: true
+            });
+        }
+    }
+};
+export { WidgetAdaptor };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rexnow/libs",
+  "version": "3.0.0",
+  "type": "module",
+  "exports": {
+    "./widget-adaptor": {
+      "types": "./dist/widget-adaptor.d.ts",
+      "import": "./dist/widget-adaptor.js"
+    },
+    "./env": "./dist/env/index.d.ts",
+    "./env.zod": "./dist/env.zod/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "provenance": true
+  },
+  "dependencies": {
+    "cheerio": "^1.2.0"
+  },
+  "devDependencies": {
+    "@rsbuild/core": "^2.2.5",
+    "@rslib/core": "^1.0.0",
+    "@rstest/adapter-rslib": "^0.11.12",
+    "@rstest/core": "^0.11.12",
+    "@types/node": "^26.5.1",
+    "ts-morph": "^28.0.0",
+    "ts-to-zod": "^5.1.0",
+    "typescript": "^7.0.2",
+    "zod": "^4.6.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/baranwang/rex-widget-libs.git",
+    "directory": "packages/libs"
+  },
+  "author": "baranwang",
+  "license": "MIT",
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "rstest"
+  }
+}