@ddysiodev/js-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 DDYS
+
+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,248 @@
+# DDYS JavaScript SDK
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Official JavaScript SDK for the DDYS Open API.
+
+Official website: [DDYS](https://ddys.io/)
+
+This package is designed as the base layer for DDYS widgets, CMS plugins, static-site starters, bots, MCP servers, and custom integrations.
+
+## Features
+
+- Covers every documented `/api/v1` endpoint.
+- Works with public read endpoints without an API key.
+- Supports authenticated endpoints with `Authorization: Bearer ddys_xxx`.
+- Includes TypeScript declarations.
+- Ships ESM and CommonJS builds.
+- Uses standard `fetch`.
+- Has zero runtime dependencies.
+- Supports custom API base URLs for Cloudflare Worker proxy deployments.
+- Provides consistent error classes, timeout handling, optional GET retry, and pagination helpers.
+
+## Install
+
+```bash
+npm install @ddysiodev/js-sdk
+```
+
+CDN URLs:
+
+```text
+https://cdn.jsdelivr.net/npm/@ddysiodev/js-sdk/dist/index.js
+https://unpkg.com/@ddysiodev/js-sdk/dist/index.js
+```
+
+Public publishing:
+
+```bash
+npm publish --access public
+```
+
+## Quick Start
+
+```js
+import { createDdysClient } from '@ddysiodev/js-sdk';
+
+const ddys = createDdysClient();
+
+const latest = await ddys.latest({ limit: 12 });
+const movie = await ddys.movies.detail('interstellar');
+const sources = await ddys.movies.sources('interstellar');
+
+console.log(latest, movie.title, sources.download);
+```
+
+## Authenticated Usage
+
+Authenticated endpoints require a user API key generated at:
+
+```text
+https://ddys.io/user/profile
+```
+
+Use the key on the server side or inside your own Worker/API route:
+
+```js
+import { createDdysClient } from '@ddysiodev/js-sdk';
+
+const ddys = createDdysClient({
+  apiKey: process.env.DDYS_API_KEY
+});
+
+const request = await ddys.requests.create({
+  title: 'Dune 2',
+  year: 2024,
+  type: 'movie',
+  douban_id: '35652650'
+});
+
+console.log(request.url);
+```
+
+Do not bundle a site owner's API key into public browser JavaScript.
+
+## Custom API Base URL
+
+Use `baseUrl` when your site routes requests through a cache proxy:
+
+```js
+const ddys = createDdysClient({
+  baseUrl: 'https://example.com/ddys-api'
+});
+```
+
+## API Methods
+
+### Movies
+
+```js
+await ddys.movies.list({ type: 'movie', sort: 'rating', page: 1, per_page: 24 });
+await ddys.movies.detail('interstellar');
+await ddys.movies.sources('interstellar');
+await ddys.movies.related('interstellar');
+await ddys.movies.comments('interstellar', { page: 1, per_page: 20 });
+```
+
+### Discovery
+
+```js
+await ddys.search({ q: 'star', type: 'movie', per_page: 10 });
+await ddys.suggest('star');
+await ddys.hot();
+await ddys.latest({ limit: 30 });
+await ddys.calendar({ year: 2026, month: 7 });
+```
+
+### Dictionaries
+
+```js
+await ddys.dictionaries.types();
+await ddys.dictionaries.genres();
+await ddys.dictionaries.regions();
+```
+
+### Collections, Shares, Requests, Activities
+
+```js
+await ddys.collections.list();
+await ddys.collections.detail('best-sci-fi');
+await ddys.shares.list();
+await ddys.shares.detail(1081);
+await ddys.requests.list();
+await ddys.activities.list({ type: 'share' });
+```
+
+### Users
+
+```js
+await ddys.users.profile('diduan');
+await ddys.me();
+```
+
+### Comments, Reports, Follow
+
+```js
+await ddys.comments.create({
+  target_type: 'movie',
+  target_id: 4786,
+  content: 'Great movie'
+});
+
+await ddys.comments.delete(12345);
+
+await ddys.reports.invalidResource({
+  movie_id: 4786,
+  resource_id: 1002
+});
+
+await ddys.follow.follow('diduan');
+await ddys.follow.unfollow('diduan');
+```
+
+## Pagination
+
+Paginated methods return:
+
+```js
+const result = await ddys.movies.list({ page: 1, per_page: 24 });
+
+console.log(result.data);
+console.log(result.meta.total);
+console.log(result.meta.total_pages);
+```
+
+`perPage` is also accepted as an alias for `per_page`.
+
+## Low-Level Request
+
+Use `request()` for advanced cases. It returns the full API envelope.
+
+```js
+const envelope = await ddys.request('/movies', {
+  query: { page: 1, per_page: 3 }
+});
+
+console.log(envelope.success, envelope.data, envelope.meta);
+```
+
+## Error Handling
+
+```js
+import { DdysApiError } from '@ddysiodev/js-sdk';
+
+try {
+  await ddys.movies.detail('missing');
+} catch (error) {
+  if (error instanceof DdysApiError) {
+    console.error(error.status, error.message, error.endpoint);
+  }
+}
+```
+
+Error classes:
+
+- `DdysApiError`
+- `DdysTimeoutError`
+- `DdysNetworkError`
+- `DdysParseError`
+
+## Runtime Support
+
+- Node.js `>=22`
+- Modern browsers
+- Cloudflare Workers
+- Vercel Edge / Netlify Edge style runtimes
+
+If a runtime does not provide global `fetch`, pass one:
+
+```js
+const ddys = createDdysClient({ fetch: customFetch });
+```
+
+## Development
+
+This project intentionally has no runtime dependencies and can build/test with Node only.
+
+```bash
+node scripts/build.mjs
+node --test test/*.test.mjs
+```
+
+When npm is available:
+
+```bash
+npm test
+```
+
+Live smoke tests are opt-in:
+
+```bash
+DDYS_LIVE_TEST=1 node test/live-smoke.mjs
+```
+
+Authenticated live smoke tests also need:
+
+```bash
+DDYS_API_KEY=ddys_xxx
+```

package/README.zh-CN.md

@@ -0,0 +1,244 @@
+# DDYS JavaScript SDK
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+DDYS Open API 官方 JavaScript SDK。
+
+官网：[低端影视](https://ddys.io/)
+
+这个包是 DDYS 开放生态的基础库，后续官方 Widgets、CMS 插件、静态站模板、Bot、MCP Server 和第三方应用都可以基于它调用 API。
+
+## 功能特点
+
+- 覆盖当前文档中的全部 `/api/v1` 接口。
+- 公开读取接口无需 API Key。
+- 支持需要鉴权的接口：`Authorization: Bearer ddys_xxx`。
+- 自带 TypeScript 类型声明。
+- 同时提供 ESM 和 CommonJS 构建。
+- 使用标准 `fetch`。
+- 零运行时依赖。
+- 支持自定义 API Base URL，方便配合 Cloudflare Worker 缓存代理。
+- 统一错误类、超时处理、可选 GET 重试和分页返回结构。
+
+## 安装
+
+```bash
+npm install @ddysiodev/js-sdk
+```
+
+CDN 地址：
+
+```text
+https://cdn.jsdelivr.net/npm/@ddysiodev/js-sdk/dist/index.js
+https://unpkg.com/@ddysiodev/js-sdk/dist/index.js
+```
+
+## 快速开始
+
+```js
+import { createDdysClient } from '@ddysiodev/js-sdk';
+
+const ddys = createDdysClient();
+
+const latest = await ddys.latest({ limit: 12 });
+const movie = await ddys.movies.detail('interstellar');
+const sources = await ddys.movies.sources('interstellar');
+
+console.log(latest, movie.title, sources.download);
+```
+
+## 鉴权接口
+
+评论、求片、举报、关注、当前用户资料等接口需要用户 API Key。
+
+API Key 在这里生成：
+
+```text
+https://ddys.io/user/profile
+```
+
+服务端使用示例：
+
+```js
+import { createDdysClient } from '@ddysiodev/js-sdk';
+
+const ddys = createDdysClient({
+  apiKey: process.env.DDYS_API_KEY
+});
+
+const request = await ddys.requests.create({
+  title: 'Dune 2',
+  year: 2024,
+  type: 'movie',
+  douban_id: '35652650'
+});
+
+console.log(request.url);
+```
+
+不要把站长自己的 API Key 打包进公开浏览器 JavaScript。公开展示类功能不需要 API Key。
+
+## 自定义 API 地址
+
+如果你通过自己的 Worker 做缓存代理，可以这样配置：
+
+```js
+const ddys = createDdysClient({
+  baseUrl: 'https://example.com/ddys-api'
+});
+```
+
+## 方法列表
+
+### 影片
+
+```js
+await ddys.movies.list({ type: 'movie', sort: 'rating', page: 1, per_page: 24 });
+await ddys.movies.detail('interstellar');
+await ddys.movies.sources('interstellar');
+await ddys.movies.related('interstellar');
+await ddys.movies.comments('interstellar', { page: 1, per_page: 20 });
+```
+
+### 搜索与发现
+
+```js
+await ddys.search({ q: '星际', type: 'movie', per_page: 10 });
+await ddys.suggest('星际');
+await ddys.hot();
+await ddys.latest({ limit: 30 });
+await ddys.calendar({ year: 2026, month: 7 });
+```
+
+### 字典
+
+```js
+await ddys.dictionaries.types();
+await ddys.dictionaries.genres();
+await ddys.dictionaries.regions();
+```
+
+### 片单、分享、求片、动态
+
+```js
+await ddys.collections.list();
+await ddys.collections.detail('best-sci-fi');
+await ddys.shares.list();
+await ddys.shares.detail(1081);
+await ddys.requests.list();
+await ddys.activities.list({ type: 'share' });
+```
+
+### 用户
+
+```js
+await ddys.users.profile('diduan');
+await ddys.me();
+```
+
+### 评论、举报、关注
+
+```js
+await ddys.comments.create({
+  target_type: 'movie',
+  target_id: 4786,
+  content: '好片'
+});
+
+await ddys.comments.delete(12345);
+
+await ddys.reports.invalidResource({
+  movie_id: 4786,
+  resource_id: 1002
+});
+
+await ddys.follow.follow('diduan');
+await ddys.follow.unfollow('diduan');
+```
+
+## 分页
+
+分页接口返回：
+
+```js
+const result = await ddys.movies.list({ page: 1, per_page: 24 });
+
+console.log(result.data);
+console.log(result.meta.total);
+console.log(result.meta.total_pages);
+```
+
+SDK 同时支持 `perPage`，会自动转换为 API 使用的 `per_page`。
+
+## 底层 request
+
+高级开发者可以直接使用 `request()`，它返回完整 API envelope：
+
+```js
+const envelope = await ddys.request('/movies', {
+  query: { page: 1, per_page: 3 }
+});
+
+console.log(envelope.success, envelope.data, envelope.meta);
+```
+
+## 错误处理
+
+```js
+import { DdysApiError } from '@ddysiodev/js-sdk';
+
+try {
+  await ddys.movies.detail('missing');
+} catch (error) {
+  if (error instanceof DdysApiError) {
+    console.error(error.status, error.message, error.endpoint);
+  }
+}
+```
+
+错误类：
+
+- `DdysApiError`
+- `DdysTimeoutError`
+- `DdysNetworkError`
+- `DdysParseError`
+
+## 运行环境
+
+- Node.js `>=22`
+- 现代浏览器
+- Cloudflare Workers
+- Vercel Edge / Netlify Edge 等运行时
+
+如果运行时没有全局 `fetch`，可以手动传入：
+
+```js
+const ddys = createDdysClient({ fetch: customFetch });
+```
+
+## 开发
+
+本项目零运行时依赖，可以只用 Node 构建和测试：
+
+```bash
+node scripts/build.mjs
+node --test test/*.test.mjs
+```
+
+如果 npm 可用：
+
+```bash
+npm test
+```
+
+线上 smoke test 默认不运行：
+
+```bash
+DDYS_LIVE_TEST=1 node test/live-smoke.mjs
+```
+
+鉴权 smoke test 还需要：
+
+```bash
+DDYS_API_KEY=ddys_xxx
+```