ddys-nextjs 0.1.0

package/.env.example

@@ -0,0 +1,7 @@
+DDYS_API_BASE_URL=https://ddys.io/api/v1
+DDYS_SITE_BASE_URL=https://ddys.io
+DDYS_API_KEY=
+DDYS_FORM_SECRET=
+DDYS_REQUEST_FORM_ENABLED=false
+DDYS_DIAGNOSTICS_ENABLED=false
+DDYS_REVALIDATE_TOKEN=

package/LICENSE

@@ -0,0 +1,21 @@
+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,196 @@
+# DDYS API Next.js Integration
+
+[中文](README.zh-CN.md)
+
+`ddys-nextjs` is the official Next.js App Router integration for the DDYS API. It provides a TypeScript API client, Server Components, Client Components, Route Handler factories, Server Actions, Metadata helpers, cache helpers, diagnostics, secure request-form handling, and ready-to-copy App Router examples.
+
+## Installation
+
+```bash
+npm install ddys-nextjs
+```
+
+For source-package consumption, add `transpilePackages`:
+
+```js
+// next.config.mjs
+const nextConfig = {
+  transpilePackages: ['ddys-nextjs'],
+  experimental: {
+    cacheComponents: true
+  }
+};
+
+export default nextConfig;
+```
+
+Import the stylesheet once:
+
+```tsx
+import 'ddys-nextjs/styles.css';
+```
+
+## Environment
+
+```env
+DDYS_API_BASE_URL=https://ddys.io/api/v1
+DDYS_SITE_BASE_URL=https://ddys.io
+DDYS_API_KEY=
+DDYS_FORM_SECRET=
+DDYS_REQUEST_FORM_ENABLED=false
+DDYS_DIAGNOSTICS_ENABLED=false
+DDYS_REVALIDATE_TOKEN=
+```
+
+`DDYS_API_KEY`, `DDYS_FORM_SECRET`, and `DDYS_REVALIDATE_TOKEN` are server-only. Do not prefix them with `NEXT_PUBLIC_`.
+
+## Server Client
+
+```tsx
+import { createDdysServerClient } from 'ddys-nextjs/server';
+
+export default async function Page() {
+  const client = createDdysServerClient();
+  const latest = await client.latest({ limit: 12 });
+  return <pre>{JSON.stringify(latest, null, 2)}</pre>;
+}
+```
+
+The client supports:
+
+`movies`, `latest`, `hot`, `search`, `suggest`, `calendar`, `movie`, `sources`, `related`, `comments`, `collections`, `collection`, `shares`, `share`, `requests`, `activities`, `user`, `types`, `genres`, `regions`, `me`, `createRequest`, `createComment`, `deleteComment`, `reportInvalidResource`, `follow`, and `unfollow`.
+
+## Components
+
+```tsx
+import { DdysView } from 'ddys-nextjs/components';
+import { DdysSearch, DdysRequestForm } from 'ddys-nextjs/components/client';
+import { createRequestFormToken, getDdysConfigFromEnv } from 'ddys-nextjs/server';
+
+export default async function Page() {
+  const config = getDdysConfigFromEnv();
+  const token = await createRequestFormToken(config, 'anonymous');
+  return (
+    <>
+      <DdysView view="latest" params={{ limit: 12 }} />
+      <DdysSearch />
+      <DdysRequestForm token={token} />
+    </>
+  );
+}
+```
+
+Available components:
+
+- `DdysView`
+- `DdysGrid`
+- `DdysCard`
+- `DdysMovieDetail`
+- `DdysSources`
+- `DdysSearch`
+- `DdysRequestForm`
+- `DdysDiagnostics`
+
+Client Component files should import interactive widgets from `ddys-nextjs/components/client` so that server-only helpers never enter a browser bundle.
+
+## Metadata And SEO
+
+`ddys-nextjs/metadata` is server-only and covers App Router metadata conventions:
+
+```tsx
+import { createDdysMetadata, createDdysMovieMetadata } from 'ddys-nextjs/metadata';
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = createDdysMetadata({
+  title: 'DDYS',
+  path: '/ddys'
+});
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return createDdysMovieMetadata(slug, {
+    path: `/ddys/movie/${slug}`
+  });
+}
+```
+
+Helpers include `createDdysMetadata`, `createDdysMovieMetadata`, `createDdysSitemap`, `createDdysRobots`, `createDdysManifest`, and `createDdysMovieJsonLd`.
+
+## App Router Pages
+
+The `examples/app-router` folder includes ready-to-copy routes:
+
+- `/ddys/latest`
+- `/ddys/hot`
+- `/ddys/movies`
+- `/ddys/search`
+- `/ddys/calendar`
+- `/ddys/movie/[slug]`
+- `/ddys/movie/[slug]/sources`
+- `/ddys/collections`
+- `/ddys/shares`
+- `/ddys/types`
+- `/ddys/genres`
+- `/ddys/regions`
+- `/ddys/request`
+- `/ddys/diagnostics`
+- `/sitemap.xml`
+- `/robots.txt`
+- `/manifest.webmanifest`
+
+## Route Handlers
+
+```ts
+// app/api/ddys/[route]/route.ts
+export { ddysProxyGET as GET } from 'ddys-nextjs/route-handlers';
+
+// app/api/ddys/request/route.ts
+export { ddysRequestPOST as POST } from 'ddys-nextjs/route-handlers';
+
+// app/api/ddys/diagnostics/route.ts
+export { ddysDiagnosticsGET as GET, ddysDiagnosticsTestPOST as POST } from 'ddys-nextjs/route-handlers';
+
+// app/api/ddys/revalidate/route.ts
+export { ddysRevalidatePOST as POST } from 'ddys-nextjs/route-handlers';
+```
+
+The proxy uses an allow-list and validates route parameters before building DDYS API paths.
+
+## Request Form
+
+Enable it only with an API key:
+
+```env
+DDYS_API_KEY=...
+DDYS_FORM_SECRET=...
+DDYS_REQUEST_FORM_ENABLED=true
+```
+
+The request service validates title, year, type, Douban ID, IMDb ID, honeypot, form token, and per-identity rate limit before using the authenticated DDYS API. The form token is created server-side and should be rendered into `DdysRequestForm`.
+
+## Cache And Revalidation
+
+The server helper maps DDYS paths to TTL and tags:
+
+- `ddys:latest`
+- `ddys:hot`
+- `ddys:movies`
+- `ddys:movie:{slug}`
+- `ddys:dictionary`
+- `ddys:community`
+
+Use `revalidateDdysAction()` or `/api/ddys/revalidate` with `DDYS_REVALIDATE_TOKEN` to revalidate by tag or path.
+
+## Diagnostics
+
+Set `DDYS_DIAGNOSTICS_ENABLED=true`, then call `/api/ddys/diagnostics`. It returns safe config, supported views, route handlers, version, runtime, and App Router status without exposing secrets.
+
+## Development Checks
+
+```bash
+node tools/check.mjs
+node --test tests/structure.test.mjs
+powershell -ExecutionPolicy Bypass -File tools/build-package.ps1 -Version 0.1.0
+```
+
+The release ZIP is written to `dist/ddys-nextjs-v0.1.0.zip`.

package/README.zh-CN.md

@@ -0,0 +1,196 @@
+# DDYS API Next.js 集成包
+
+[English](README.md)
+
+`ddys-nextjs` 是低端影视 API 的官方 Next.js App Router 集成包，提供 TypeScript API Client、Server Components、Client Components、Route Handler 工厂、Server Actions、Metadata 辅助、缓存辅助、诊断接口、安全求片表单和可直接复制的 App Router 示例。
+
+## 安装
+
+```bash
+npm install ddys-nextjs
+```
+
+如果以源码包方式使用，请在 Next.js 配置中加入 `transpilePackages`：
+
+```js
+// next.config.mjs
+const nextConfig = {
+  transpilePackages: ['ddys-nextjs'],
+  experimental: {
+    cacheComponents: true
+  }
+};
+
+export default nextConfig;
+```
+
+全局引入样式：
+
+```tsx
+import 'ddys-nextjs/styles.css';
+```
+
+## 环境变量
+
+```env
+DDYS_API_BASE_URL=https://ddys.io/api/v1
+DDYS_SITE_BASE_URL=https://ddys.io
+DDYS_API_KEY=
+DDYS_FORM_SECRET=
+DDYS_REQUEST_FORM_ENABLED=false
+DDYS_DIAGNOSTICS_ENABLED=false
+DDYS_REVALIDATE_TOKEN=
+```
+
+`DDYS_API_KEY`、`DDYS_FORM_SECRET`、`DDYS_REVALIDATE_TOKEN` 必须只在服务端使用，不要加 `NEXT_PUBLIC_` 前缀。
+
+## 服务端 Client
+
+```tsx
+import { createDdysServerClient } from 'ddys-nextjs/server';
+
+export default async function Page() {
+  const client = createDdysServerClient();
+  const latest = await client.latest({ limit: 12 });
+  return <pre>{JSON.stringify(latest, null, 2)}</pre>;
+}
+```
+
+Client 覆盖：
+
+`movies`、`latest`、`hot`、`search`、`suggest`、`calendar`、`movie`、`sources`、`related`、`comments`、`collections`、`collection`、`shares`、`share`、`requests`、`activities`、`user`、`types`、`genres`、`regions`、`me`、`createRequest`、`createComment`、`deleteComment`、`reportInvalidResource`、`follow`、`unfollow`。
+
+## 组件
+
+```tsx
+import { DdysView } from 'ddys-nextjs/components';
+import { DdysSearch, DdysRequestForm } from 'ddys-nextjs/components/client';
+import { createRequestFormToken, getDdysConfigFromEnv } from 'ddys-nextjs/server';
+
+export default async function Page() {
+  const config = getDdysConfigFromEnv();
+  const token = await createRequestFormToken(config, 'anonymous');
+  return (
+    <>
+      <DdysView view="latest" params={{ limit: 12 }} />
+      <DdysSearch />
+      <DdysRequestForm token={token} />
+    </>
+  );
+}
+```
+
+组件包括：
+
+- `DdysView`
+- `DdysGrid`
+- `DdysCard`
+- `DdysMovieDetail`
+- `DdysSources`
+- `DdysSearch`
+- `DdysRequestForm`
+- `DdysDiagnostics`
+
+Client Component 文件应从 `ddys-nextjs/components/client` 导入交互组件，避免 server-only 辅助逻辑进入浏览器 bundle。
+
+## Metadata 与 SEO
+
+`ddys-nextjs/metadata` 是服务端专用入口，覆盖 App Router 的 metadata 约定：
+
+```tsx
+import { createDdysMetadata, createDdysMovieMetadata } from 'ddys-nextjs/metadata';
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = createDdysMetadata({
+  title: 'DDYS',
+  path: '/ddys'
+});
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return createDdysMovieMetadata(slug, {
+    path: `/ddys/movie/${slug}`
+  });
+}
+```
+
+辅助函数包括 `createDdysMetadata`、`createDdysMovieMetadata`、`createDdysSitemap`、`createDdysRobots`、`createDdysManifest`、`createDdysMovieJsonLd`。
+
+## App Router 页面
+
+`examples/app-router` 目录提供可复制路由：
+
+- `/ddys/latest`
+- `/ddys/hot`
+- `/ddys/movies`
+- `/ddys/search`
+- `/ddys/calendar`
+- `/ddys/movie/[slug]`
+- `/ddys/movie/[slug]/sources`
+- `/ddys/collections`
+- `/ddys/shares`
+- `/ddys/types`
+- `/ddys/genres`
+- `/ddys/regions`
+- `/ddys/request`
+- `/ddys/diagnostics`
+- `/sitemap.xml`
+- `/robots.txt`
+- `/manifest.webmanifest`
+
+## Route Handlers
+
+```ts
+// app/api/ddys/[route]/route.ts
+export { ddysProxyGET as GET } from 'ddys-nextjs/route-handlers';
+
+// app/api/ddys/request/route.ts
+export { ddysRequestPOST as POST } from 'ddys-nextjs/route-handlers';
+
+// app/api/ddys/diagnostics/route.ts
+export { ddysDiagnosticsGET as GET, ddysDiagnosticsTestPOST as POST } from 'ddys-nextjs/route-handlers';
+
+// app/api/ddys/revalidate/route.ts
+export { ddysRevalidatePOST as POST } from 'ddys-nextjs/route-handlers';
+```
+
+代理入口使用 allow-list，并在拼接 DDYS API 路径前校验 route 参数。
+
+## 求片表单
+
+只有配置 API Key 后才建议开启：
+
+```env
+DDYS_API_KEY=...
+DDYS_FORM_SECRET=...
+DDYS_REQUEST_FORM_ENABLED=true
+```
+
+求片服务会在调用低端影视认证 API 前校验标题、年份、类型、豆瓣 ID、IMDb ID、蜜罐字段、表单 token 和单身份提交频率。表单 token 在服务端生成后传给 `DdysRequestForm`。
+
+## 缓存与刷新
+
+服务端辅助会把 DDYS 路径映射到 TTL 和 tag：
+
+- `ddys:latest`
+- `ddys:hot`
+- `ddys:movies`
+- `ddys:movie:{slug}`
+- `ddys:dictionary`
+- `ddys:community`
+
+使用 `revalidateDdysAction()` 或 `/api/ddys/revalidate`，配合 `DDYS_REVALIDATE_TOKEN` 按 tag 或 path 刷新缓存。
+
+## 诊断
+
+设置 `DDYS_DIAGNOSTICS_ENABLED=true` 后访问 `/api/ddys/diagnostics`。它会返回脱敏配置、支持的视图、Route Handlers、版本、运行时和 App Router 状态，不暴露密钥。
+
+## 开发检查
+
+```bash
+node tools/check.mjs
+node --test tests/structure.test.mjs
+powershell -ExecutionPolicy Bypass -File tools/build-package.ps1 -Version 0.1.0
+```
+
+发布 ZIP 会生成到 `dist/ddys-nextjs-v0.1.0.zip`。

package/examples/app-router/app/api/ddys/[route]/route.ts

@@ -0,0 +1 @@
+export { ddysProxyGET as GET } from 'ddys-nextjs/route-handlers';

package/examples/app-router/app/api/ddys/diagnostics/route.ts

@@ -0,0 +1 @@
+export { ddysDiagnosticsGET as GET, ddysDiagnosticsTestPOST as POST } from 'ddys-nextjs/route-handlers';

package/examples/app-router/app/api/ddys/request/route.ts

@@ -0,0 +1 @@
+export { ddysRequestPOST as POST } from 'ddys-nextjs/route-handlers';

package/examples/app-router/app/api/ddys/revalidate/route.ts

@@ -0,0 +1 @@
+export { ddysRevalidatePOST as POST } from 'ddys-nextjs/route-handlers';

package/examples/app-router/app/ddys/calendar/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | undefined>> }) {
+  return <DdysView view="calendar" params={await searchParams} />;
+}

package/examples/app-router/app/ddys/collections/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | undefined>> }) {
+  return <DdysView view="collections" params={await searchParams} />;
+}

package/examples/app-router/app/ddys/diagnostics/page.tsx

@@ -0,0 +1,5 @@
+import { DdysDiagnostics } from 'ddys-nextjs/components/client';
+
+export default function Page() {
+  return <DdysDiagnostics />;
+}

package/examples/app-router/app/ddys/genres/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default function Page() {
+  return <DdysView view="genres" />;
+}

package/examples/app-router/app/ddys/hot/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default function Page() {
+  return <DdysView view="hot" params={{ limit: 12 }} />;
+}

package/examples/app-router/app/ddys/latest/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default function Page() {
+  return <DdysView view="latest" params={{ limit: 12 }} />;
+}

package/examples/app-router/app/ddys/layout.tsx

@@ -0,0 +1,13 @@
+import 'ddys-nextjs/styles.css';
+import { createDdysMetadata } from 'ddys-nextjs/metadata';
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+
+export const metadata: Metadata = createDdysMetadata({
+  title: 'DDYS',
+  path: '/ddys'
+});
+
+export default function DdysLayout({ children }: { children: ReactNode }) {
+  return <main style={{ margin: '0 auto', maxWidth: 1180, padding: '24px 18px' }}>{children}</main>;
+}

package/examples/app-router/app/ddys/movie/[slug]/page.tsx

@@ -0,0 +1,15 @@
+import { DdysView } from 'ddys-nextjs/components';
+import { createDdysMovieMetadata } from 'ddys-nextjs/metadata';
+import type { Metadata } from 'next';
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
+  const { slug } = await params;
+  return createDdysMovieMetadata(slug, {
+    path: `/ddys/movie/${encodeURIComponent(slug)}`
+  });
+}
+
+export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return <DdysView view="movie" params={{ slug }} />;
+}

package/examples/app-router/app/ddys/movie/[slug]/sources/page.tsx

@@ -0,0 +1,12 @@
+import { createDdysServerClient } from 'ddys-nextjs/server';
+import { DdysSources } from 'ddys-nextjs/components';
+import type { DdysResource } from 'ddys-nextjs';
+
+export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const sources = await createDdysServerClient().sources(slug) as Record<string, unknown>;
+  const groups = {
+    Resources: (Array.isArray(sources) ? sources : Array.isArray(sources.resources) ? sources.resources : []) as DdysResource[]
+  };
+  return <DdysSources groups={groups} />;
+}

package/examples/app-router/app/ddys/movies/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | undefined>> }) {
+  return <DdysView view="movies" params={await searchParams} />;
+}

package/examples/app-router/app/ddys/regions/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default function Page() {
+  return <DdysView view="regions" />;
+}

package/examples/app-router/app/ddys/request/page.tsx

@@ -0,0 +1,8 @@
+import { DdysRequestForm } from 'ddys-nextjs/components/client';
+import { createRequestFormToken, getDdysConfigFromEnv } from 'ddys-nextjs/server';
+
+export default async function Page() {
+  const config = getDdysConfigFromEnv();
+  const token = await createRequestFormToken(config, 'anonymous');
+  return <DdysRequestForm token={token} honeypotField={config.requestForm.honeypotField} />;
+}

package/examples/app-router/app/ddys/search/page.tsx

@@ -0,0 +1,5 @@
+import { DdysSearch } from 'ddys-nextjs/components';
+
+export default function Page() {
+  return <DdysSearch />;
+}

package/examples/app-router/app/ddys/shares/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default async function Page({ searchParams }: { searchParams: Promise<Record<string, string | undefined>> }) {
+  return <DdysView view="shares" params={await searchParams} />;
+}

package/examples/app-router/app/ddys/types/page.tsx

@@ -0,0 +1,5 @@
+import { DdysView } from 'ddys-nextjs/components';
+
+export default function Page() {
+  return <DdysView view="types" />;
+}

package/examples/app-router/app/manifest.ts

@@ -0,0 +1,9 @@
+import { createDdysManifest } from 'ddys-nextjs/metadata';
+
+export default function manifest() {
+  return createDdysManifest({
+    name: 'DDYS',
+    shortName: 'DDYS',
+    startUrl: '/ddys'
+  });
+}

package/examples/app-router/app/robots.ts

@@ -0,0 +1,5 @@
+import { createDdysRobots } from 'ddys-nextjs/metadata';
+
+export default function robots() {
+  return createDdysRobots();
+}

package/examples/app-router/app/sitemap.ts

@@ -0,0 +1,7 @@
+import { createDdysSitemap } from 'ddys-nextjs/metadata';
+
+export default function sitemap() {
+  return createDdysSitemap({
+    basePath: '/ddys'
+  });
+}

package/next.config.example.mjs

@@ -0,0 +1,9 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ['ddys-nextjs'],
+  experimental: {
+    cacheComponents: true
+  }
+};
+
+export default nextConfig;