ddys-nextjs 0.1.0

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "ddys-nextjs",
+  "version": "0.1.0",
+  "description": "Official Next.js integration for the DDYS API with App Router pages, Server Components, Route Handlers, metadata, caching, diagnostics, and request form.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://ddys.io",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ddysiodev/ddys-nextjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ddysiodev/ddys-nextjs/issues"
+  },
+  "keywords": [
+    "ddys",
+    "nextjs",
+    "next",
+    "react",
+    "app-router",
+    "server-components",
+    "route-handlers",
+    "metadata",
+    "seo",
+    "movies",
+    "video",
+    "api"
+  ],
+  "sideEffects": [
+    "./src/styles/ddys.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "import": "./src/client/index.ts"
+    },
+    "./server": {
+      "types": "./src/server/index.ts",
+      "import": "./src/server/index.ts"
+    },
+    "./components": {
+      "types": "./src/components/index.ts",
+      "import": "./src/components/index.ts"
+    },
+    "./components/client": {
+      "types": "./src/components/client.ts",
+      "import": "./src/components/client.ts"
+    },
+    "./actions": {
+      "types": "./src/actions/index.ts",
+      "import": "./src/actions/index.ts"
+    },
+    "./route-handlers": {
+      "types": "./src/route-handlers/index.ts",
+      "import": "./src/route-handlers/index.ts"
+    },
+    "./metadata": {
+      "types": "./src/metadata/index.ts",
+      "import": "./src/metadata/index.ts"
+    },
+    "./styles.css": "./src/styles/ddys.css"
+  },
+  "files": [
+    "src",
+    "examples",
+    "public",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    ".env.example",
+    "next.config.example.mjs"
+  ],
+  "peerDependencies": {
+    "next": ">=14.2.0",
+    "react": ">=18.2.0 || >=19.0.0",
+    "react-dom": ">=18.2.0 || >=19.0.0"
+  },
+  "dependencies": {
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "check": "node tools/check.mjs",
+    "test": "node tools/check.mjs && node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,2 @@
+export { submitDdysRequestAction, type DdysActionState } from './request';
+export { revalidateDdysAction } from './revalidate';

package/src/actions/request.ts

@@ -0,0 +1,26 @@
+'use server';
+
+import type { DdysConfigInput } from '../client/config';
+import { getDdysConfigFromEnv } from '../server/config';
+import { submitDdysRequest } from '../server/request-service';
+import { formDataToObject } from '../utils/security';
+
+export interface DdysActionState {
+  success: boolean;
+  message: string;
+  data?: unknown;
+}
+
+export async function submitDdysRequestAction(_state: DdysActionState, formData: FormData, configInput: DdysConfigInput = {}): Promise<DdysActionState> {
+  const config = getDdysConfigFromEnv(configInput);
+  const input = formDataToObject(formData);
+  try {
+    const data = await submitDdysRequest(input, config, {
+      identity: input.ddys_identity || 'anonymous',
+      token: input.ddys_token
+    });
+    return { success: true, message: 'Request submitted.', data };
+  } catch (error) {
+    return { success: false, message: error instanceof Error ? error.message : 'Request failed.' };
+  }
+}

package/src/actions/revalidate.ts

@@ -0,0 +1,15 @@
+'use server';
+
+import { revalidateDdys } from '../server/cache';
+
+export async function revalidateDdysAction(input: { tag?: string; tagProfile?: string; path?: string; pathType?: 'layout' | 'page'; token?: string }) {
+  const expected = process.env.DDYS_REVALIDATE_TOKEN ?? '';
+  if (!expected || input.token !== expected) {
+    return { success: false, message: 'Invalid revalidation token.' };
+  }
+  if (!input.tag && !input.path) {
+    return { success: false, message: 'Missing tag or path.' };
+  }
+  revalidateDdys({ tag: input.tag, tagProfile: input.tagProfile, path: input.path, pathType: input.pathType });
+  return { success: true };
+}

package/src/client/client.ts

@@ -0,0 +1,194 @@
+import { DdysError } from './error';
+import { DEFAULT_DDYS_CONFIG, type DdysConfig, type DdysConfigInput, mergeDdysConfig } from './config';
+import type { DdysApiResponse, DdysPaginated, DdysQuery, DdysRequestInput } from '../types/ddys';
+import { buildQuery, cleanQuery, normalizeBaseUrl, positiveId, routeSegment, toSearchParams } from '../utils/security';
+
+export interface DdysRequestOptions {
+  auth?: boolean;
+  noCache?: boolean;
+  cacheTtl?: number;
+  next?: {
+    revalidate?: number | false;
+    tags?: string[];
+  };
+  cache?: RequestCache;
+  signal?: AbortSignal;
+}
+
+export type DdysFetch = (input: string | URL | Request, init?: RequestInit & { next?: DdysRequestOptions['next'] }) => Promise<Response>;
+
+export class DdysClient {
+  readonly config: DdysConfig;
+  private readonly fetcher: DdysFetch;
+
+  constructor(config: DdysConfigInput = {}, fetcher: DdysFetch = fetch) {
+    const merged = mergeDdysConfig(config);
+    this.config = {
+      ...merged,
+      apiBaseUrl: normalizeBaseUrl(merged.apiBaseUrl, DEFAULT_DDYS_CONFIG.apiBaseUrl),
+      siteBaseUrl: normalizeBaseUrl(merged.siteBaseUrl, DEFAULT_DDYS_CONFIG.siteBaseUrl)
+    };
+    this.fetcher = fetcher;
+  }
+
+  async request<T = unknown>(method: string, path: string, query: DdysQuery = {}, body?: unknown, options: DdysRequestOptions = {}): Promise<DdysApiResponse<T>> {
+    method = method.toUpperCase();
+    path = `/${path.replace(/^\/+/, '')}`;
+    const clean = cleanQuery(query);
+    const auth = Boolean(options.auth);
+    if (auth && !this.config.apiKey) {
+      throw new DdysError('DDYS API Key is not configured.', 401, method, path);
+    }
+
+    return this.sendWithRetry<T>(method, path, clean, body, auth, options);
+  }
+
+  async get<T = unknown>(path: string, query: DdysQuery = {}, options: DdysRequestOptions = {}): Promise<DdysApiResponse<T>> {
+    return this.request<T>('GET', path, query, undefined, options);
+  }
+
+  async post<T = unknown>(path: string, body: unknown = {}, options: DdysRequestOptions = {}): Promise<DdysApiResponse<T>> {
+    return this.request<T>('POST', path, {}, body, options);
+  }
+
+  async delete<T = unknown>(path: string, options: DdysRequestOptions = {}): Promise<DdysApiResponse<T>> {
+    return this.request<T>('DELETE', path, {}, undefined, options);
+  }
+
+  async data<T = unknown>(path: string, query: DdysQuery = {}, options: DdysRequestOptions = {}): Promise<T> {
+    const payload = await this.get<T>(path, query, options);
+    return (payload.data ?? payload) as T;
+  }
+
+  async paginated<T = unknown>(path: string, query: DdysQuery = {}, options: DdysRequestOptions = {}): Promise<DdysPaginated<T>> {
+    const payload = await this.get<T[]>(path, query, options);
+    return {
+      data: Array.isArray(payload.data) ? payload.data : [],
+      meta: payload.meta ?? {}
+    };
+  }
+
+  movies(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated('/movies', this.query(params, ['type', 'genre', 'region', 'year', 'sort', 'page', 'per_page']), options); }
+  latest(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.data('/latest', this.query(params, ['type', 'genre', 'region', 'year', 'limit']), options); }
+  hot(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.data('/hot', this.query(params, ['type', 'genre', 'region', 'limit']), options); }
+  search(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated('/search', this.query(params, ['q', 'type', 'page', 'per_page']), options); }
+  suggest(q: string, params: DdysQuery = {}, options?: DdysRequestOptions) { return this.data('/suggest', this.query({ ...params, q }, ['q', 'limit']), options); }
+  calendar(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.data('/calendar', this.query(params, ['year', 'month']), options); }
+  movie(slug: string, options?: DdysRequestOptions) { return this.data(`/movies/${routeSegment(slug, 'movie slug')}`, {}, options); }
+  sources(slug: string, options?: DdysRequestOptions) { return this.data(`/movies/${routeSegment(slug, 'movie slug')}/sources`, {}, options); }
+  related(slug: string, options?: DdysRequestOptions) { return this.data(`/movies/${routeSegment(slug, 'movie slug')}/related`, {}, options); }
+  comments(slug: string, params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated(`/movies/${routeSegment(slug, 'movie slug')}/comments`, this.query(params, ['page', 'per_page']), options); }
+  collections(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated('/collections', this.query(params, ['page', 'per_page']), options); }
+  collection(slug: string, params: DdysQuery = {}, options?: DdysRequestOptions) { return this.data(`/collections/${routeSegment(slug, 'collection slug')}`, this.query(params, ['page', 'per_page']), options); }
+  shares(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated('/shares', this.query(params, ['page', 'per_page']), options); }
+  share(id: string | number, options?: DdysRequestOptions) { return this.data(`/shares/${positiveId(id, 'share ID')}`, {}, options); }
+  requests(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated('/requests', this.query(params, ['page', 'per_page']), options); }
+  activities(params: DdysQuery = {}, options?: DdysRequestOptions) { return this.paginated('/activities', this.query(params, ['type', 'page', 'per_page']), options); }
+  user(username: string, options?: DdysRequestOptions) { return this.data(`/user/${routeSegment(username, 'username')}`, {}, options); }
+  types(options?: DdysRequestOptions) { return this.data('/types', {}, options); }
+  genres(options?: DdysRequestOptions) { return this.data('/genres', {}, options); }
+  regions(options?: DdysRequestOptions) { return this.data('/regions', {}, options); }
+  me(options?: DdysRequestOptions) { return this.unwrap(this.get('/me', {}, { ...options, auth: true, noCache: true })); }
+  createRequest(input: DdysRequestInput, options?: DdysRequestOptions) { return this.unwrap(this.post('/requests', input, { ...options, auth: true, noCache: true })); }
+  createComment(input: Record<string, unknown>, options?: DdysRequestOptions) { return this.unwrap(this.post('/comments', input, { ...options, auth: true, noCache: true })); }
+  deleteComment(id: string | number, options?: DdysRequestOptions) { return this.unwrap(this.delete(`/comments/${positiveId(id, 'comment ID')}`, { ...options, auth: true, noCache: true })); }
+  reportInvalidResource(input: Record<string, unknown>, options?: DdysRequestOptions) { return this.unwrap(this.post('/report', input, { ...options, auth: true, noCache: true })); }
+  follow(username: string, options?: DdysRequestOptions) { return this.setFollow(username, 'follow', options); }
+  unfollow(username: string, options?: DdysRequestOptions) { return this.setFollow(username, 'unfollow', options); }
+
+  async setFollow(username: string, action: 'follow' | 'unfollow', options?: DdysRequestOptions) {
+    return this.unwrap(this.post('/follow', { username, action }, { ...options, auth: true, noCache: true }));
+  }
+
+  async proxy(route: string, query: DdysQuery = {}, options?: DdysRequestOptions): Promise<DdysApiResponse> {
+    route = String(route || 'latest').toLowerCase();
+    if (!this.config.proxy.allowRoutes.includes(route)) {
+      throw new DdysError('Route is not allowed.', 403, 'GET', '/proxy');
+    }
+    const path = this.proxyPath(route, query);
+    if (!path) throw new DdysError('Invalid route parameters.', 400, 'GET', '/proxy');
+    return this.get(path, this.query(query, ['type', 'genre', 'region', 'year', 'sort', 'page', 'per_page', 'limit', 'q', 'month']), options);
+  }
+
+  private async unwrap<T>(promise: Promise<DdysApiResponse<T>>): Promise<T | DdysApiResponse<T>> {
+    const payload = await promise;
+    return payload.data ?? payload;
+  }
+
+  private query(params: DdysQuery, keys: string[]) {
+    return buildQuery(params, keys, this.config.security);
+  }
+
+  private proxyPath(route: string, query: DdysQuery): string {
+    const slug = String(query.slug ?? '');
+    const id = String(query.id ?? '');
+    const username = String(query.username ?? '');
+    switch (route) {
+      case 'movies': return '/movies';
+      case 'latest': return '/latest';
+      case 'hot': return '/hot';
+      case 'search': return '/search';
+      case 'suggest': return '/suggest';
+      case 'calendar': return '/calendar';
+      case 'movie': return slug ? `/movies/${routeSegment(slug, 'movie slug')}` : '';
+      case 'sources': return slug ? `/movies/${routeSegment(slug, 'movie slug')}/sources` : '';
+      case 'related': return slug ? `/movies/${routeSegment(slug, 'movie slug')}/related` : '';
+      case 'comments': return slug ? `/movies/${routeSegment(slug, 'movie slug')}/comments` : '';
+      case 'collections': return '/collections';
+      case 'collection': return slug ? `/collections/${routeSegment(slug, 'collection slug')}` : '';
+      case 'shares': return '/shares';
+      case 'share': return id ? `/shares/${positiveId(id, 'share ID')}` : '';
+      case 'requests': return '/requests';
+      case 'activities': return '/activities';
+      case 'user': return username ? `/user/${routeSegment(username, 'username')}` : '';
+      case 'types': return '/types';
+      case 'genres': return '/genres';
+      case 'regions': return '/regions';
+      default: return '';
+    }
+  }
+
+  private async sendWithRetry<T>(method: string, path: string, query: Record<string, string>, body: unknown, auth: boolean, options: DdysRequestOptions): Promise<DdysApiResponse<T>> {
+    const attempts = Math.max(1, this.config.retryTimes + 1);
+    let last: unknown;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        const qs = toSearchParams(query);
+        const url = `${this.config.apiBaseUrl}${path}${qs ? `?${qs}` : ''}`;
+        const controller = options.signal ? undefined : new AbortController();
+        const timeout = controller ? setTimeout(() => controller.abort(), this.config.timeout * 1000) : undefined;
+        const headers = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            ...(typeof window === 'undefined' ? { 'User-Agent': this.config.userAgent } : {}),
+            ...(auth ? { Authorization: `Bearer ${this.config.apiKey}` } : {})
+        };
+        let response: Response;
+        try {
+          response = await this.fetcher(url, {
+            method,
+            headers,
+            body: method === 'GET' || body === undefined ? undefined : JSON.stringify(body),
+            cache: options.noCache ? 'no-store' : options.cache,
+            next: options.noCache ? undefined : options.next,
+            signal: options.signal ?? controller?.signal
+          });
+        } finally {
+          if (timeout) clearTimeout(timeout);
+        }
+        const json = await response.json().catch(() => null);
+        if (!json || typeof json !== 'object') throw new DdysError('DDYS API returned invalid JSON.', 502, method, path);
+        if (!response.ok) throw new DdysError(`DDYS API HTTP ${response.status}.`, response.status, method, path, json);
+        if ('success' in json && json.success === false) throw new DdysError(String(json.message || 'DDYS API request failed.'), 502, method, path, json);
+        return json as DdysApiResponse<T>;
+      } catch (error) {
+        last = error;
+        if (error instanceof DdysError && error.status >= 400 && error.status < 500) throw error;
+        if (method !== 'GET' || attempt >= attempts) break;
+        await new Promise((resolve) => setTimeout(resolve, this.config.retrySleep));
+      }
+    }
+    if (last instanceof DdysError) throw last;
+    throw new DdysError(`DDYS API request failed: ${last instanceof Error ? last.message : 'unknown error'}`, 0, method, path, last);
+  }
+}

package/src/client/config.ts

@@ -0,0 +1,111 @@
+export interface DdysCacheConfig {
+  defaultTtl: number;
+  dictionaryTtl: number;
+  freshTtl: number;
+  listTtl: number;
+  detailTtl: number;
+  communityTtl: number;
+}
+
+export interface DdysRequestFormConfig {
+  enabled: boolean;
+  csrf: boolean;
+  honeypotField: string;
+  rateLimitSeconds: number;
+  tokenTtlSeconds: number;
+  secret?: string;
+}
+
+export interface DdysProxyConfig {
+  enabled: boolean;
+  allowRoutes: string[];
+}
+
+export interface DdysSecurityConfig {
+  maxLimit: number;
+  maxPerPage: number;
+  maxPage: number;
+  allowedResourceProtocols: string[];
+}
+
+export interface DdysConfig {
+  apiBaseUrl: string;
+  siteBaseUrl: string;
+  apiKey?: string;
+  timeout: number;
+  retryTimes: number;
+  retrySleep: number;
+  userAgent: string;
+  cache: DdysCacheConfig;
+  proxy: DdysProxyConfig;
+  requestForm: DdysRequestFormConfig;
+  diagnostics: {
+    enabled: boolean;
+  };
+  security: DdysSecurityConfig;
+}
+
+export const DDYS_VERSION = '0.1.0';
+
+export const DEFAULT_DDYS_CONFIG: DdysConfig = {
+  apiBaseUrl: 'https://ddys.io/api/v1',
+  siteBaseUrl: 'https://ddys.io',
+  apiKey: '',
+  timeout: 12,
+  retryTimes: 1,
+  retrySleep: 150,
+  userAgent: `ddys-nextjs/${DDYS_VERSION}`,
+  cache: {
+    defaultTtl: 300,
+    dictionaryTtl: 86400,
+    freshTtl: 300,
+    listTtl: 600,
+    detailTtl: 1800,
+    communityTtl: 120
+  },
+  proxy: {
+    enabled: true,
+    allowRoutes: [
+      'movies', 'latest', 'hot', 'search', 'suggest', 'calendar',
+      'movie', 'sources', 'related', 'comments',
+      'collections', 'collection', 'shares', 'share',
+      'requests', 'activities', 'user', 'types', 'genres', 'regions'
+    ]
+  },
+  requestForm: {
+    enabled: false,
+    csrf: true,
+    honeypotField: 'ddys_website',
+    rateLimitSeconds: 60,
+    tokenTtlSeconds: 1800
+  },
+  diagnostics: {
+    enabled: false
+  },
+  security: {
+    maxLimit: 50,
+    maxPerPage: 50,
+    maxPage: 999,
+    allowedResourceProtocols: ['http:', 'https:', 'magnet:', 'ed2k:', 'thunder:']
+  }
+};
+
+export type DdysConfigInput = Partial<Omit<DdysConfig, 'cache' | 'proxy' | 'requestForm' | 'diagnostics' | 'security'>> & {
+  cache?: Partial<DdysCacheConfig>;
+  proxy?: Partial<DdysProxyConfig>;
+  requestForm?: Partial<DdysRequestFormConfig>;
+  diagnostics?: Partial<DdysConfig['diagnostics']>;
+  security?: Partial<DdysSecurityConfig>;
+};
+
+export function mergeDdysConfig(input: DdysConfigInput = {}): DdysConfig {
+  return {
+    ...DEFAULT_DDYS_CONFIG,
+    ...input,
+    cache: { ...DEFAULT_DDYS_CONFIG.cache, ...input.cache },
+    proxy: { ...DEFAULT_DDYS_CONFIG.proxy, ...input.proxy },
+    requestForm: { ...DEFAULT_DDYS_CONFIG.requestForm, ...input.requestForm },
+    diagnostics: { ...DEFAULT_DDYS_CONFIG.diagnostics, ...input.diagnostics },
+    security: { ...DEFAULT_DDYS_CONFIG.security, ...input.security }
+  };
+}

package/src/client/error.ts

@@ -0,0 +1,15 @@
+export class DdysError extends Error {
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+  readonly context: unknown;
+
+  constructor(message: string, status = 0, method = '', path = '', context?: unknown) {
+    super(message);
+    this.name = 'DdysError';
+    this.status = status;
+    this.method = method;
+    this.path = path;
+    this.context = context;
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,13 @@
+export { DdysClient } from './client';
+export { DdysError } from './error';
+export {
+  DDYS_VERSION,
+  DEFAULT_DDYS_CONFIG,
+  mergeDdysConfig,
+  type DdysCacheConfig,
+  type DdysConfig,
+  type DdysConfigInput,
+  type DdysProxyConfig,
+  type DdysRequestFormConfig,
+  type DdysSecurityConfig
+} from './config';

package/src/components/card.tsx

@@ -0,0 +1,38 @@
+import type { DdysDisplayOptions, DdysItem } from '../types/ddys';
+import { itemMeta, itemPoster, itemSummary, itemTitle, itemUrl } from './utils';
+
+export interface DdysCardProps {
+  item: DdysItem;
+  display?: DdysDisplayOptions;
+  siteBaseUrl?: string;
+}
+
+export function DdysCard({ item, display = {}, siteBaseUrl }: DdysCardProps) {
+  const title = itemTitle(item);
+  const poster = itemPoster(item);
+  const url = itemUrl(item, siteBaseUrl);
+  const meta = itemMeta(item);
+  const summary = itemSummary(item);
+  const showPoster = display.showPoster ?? true;
+  const showSummary = display.showSummary ?? true;
+  const showSourceLink = display.showSourceLink ?? true;
+  const target = display.target ?? '_blank';
+
+  return (
+    <article className="ddys-next-card">
+      {showPoster && poster ? (
+        <div className="ddys-next-poster">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img src={poster} alt={title} loading="lazy" />
+        </div>
+      ) : null}
+      <div className="ddys-next-card-body">
+        <h3 className="ddys-next-title">
+          {url && showSourceLink ? <a href={url} target={target} rel="noopener noreferrer">{title}</a> : title}
+        </h3>
+        {meta.length ? <div className="ddys-next-meta">{meta.join(' / ')}</div> : null}
+        {showSummary && summary ? <div className="ddys-next-summary">{summary}</div> : null}
+      </div>
+    </article>
+  );
+}

package/src/components/client.ts

@@ -0,0 +1,3 @@
+export { DdysDiagnostics } from './diagnostics';
+export { DdysRequestForm, type DdysRequestFormProps } from './request-form';
+export { DdysSearch, type DdysSearchProps } from './search';

package/src/components/diagnostics.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { useState } from 'react';
+
+export function DdysDiagnostics({ endpoint = '/api/ddys/diagnostics' }: { endpoint?: string }) {
+  const [status, setStatus] = useState('Ready.');
+  const [data, setData] = useState<unknown>(null);
+
+  async function load() {
+    setStatus('Loading...');
+    const response = await fetch(endpoint, { credentials: 'same-origin' });
+    const json = await response.json().catch(() => ({ success: false, message: 'Invalid JSON response.' }));
+    setData(json);
+    setStatus(json.success ? 'Diagnostics loaded.' : json.message || `HTTP ${response.status}`);
+  }
+
+  async function test() {
+    setStatus('Testing...');
+    const response = await fetch(endpoint, { method: 'POST', credentials: 'same-origin' });
+    const json = await response.json().catch(() => ({ success: false, message: 'Invalid JSON response.' }));
+    setData(json);
+    setStatus(json.success ? 'Connection OK.' : json.message || `HTTP ${response.status}`);
+  }
+
+  return (
+    <section className="ddys-next-diagnostics">
+      <div className="ddys-next-actions">
+        <button type="button" onClick={load}>Load diagnostics</button>
+        <button type="button" onClick={test}>Test API</button>
+      </div>
+      <p className="ddys-next-status" role="status">{status}</p>
+      {data ? <pre>{JSON.stringify(data, null, 2)}</pre> : null}
+    </section>
+  );
+}

package/src/components/grid.tsx

@@ -0,0 +1,27 @@
+import type { DdysDisplayOptions, DdysItem } from '../types/ddys';
+import type { CSSProperties } from 'react';
+import { DdysCard } from './card';
+
+export interface DdysGridProps {
+  items: DdysItem[];
+  display?: DdysDisplayOptions;
+  siteBaseUrl?: string;
+  emptyText?: string;
+}
+
+export function DdysGrid({ items, display = {}, siteBaseUrl, emptyText = 'No DDYS content found.' }: DdysGridProps) {
+  const columns = Math.max(1, Math.min(6, display.columns ?? 4));
+  const layout = display.layout ?? 'grid';
+  const theme = display.theme ?? 'auto';
+  if (!items.length) {
+    return <div className={`ddys-next ddys-next-theme-${theme}`}><div className="ddys-next-empty">{emptyText}</div></div>;
+  }
+
+  return (
+    <div className={`ddys-next ddys-next-theme-${theme} ddys-next-layout-${layout}`} style={{ '--ddys-next-columns': columns } as CSSProperties}>
+      <div className="ddys-next-items">
+        {items.map((item, index) => <DdysCard key={String(item.id ?? item.slug ?? index)} item={item} display={display} siteBaseUrl={siteBaseUrl} />)}
+      </div>
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,8 @@
+export { DdysCard, type DdysCardProps } from './card';
+export { DdysDiagnostics } from './diagnostics';
+export { DdysGrid, type DdysGridProps } from './grid';
+export { DdysMovieDetail, type DdysMovieDetailProps } from './movie-detail';
+export { DdysRequestForm, type DdysRequestFormProps } from './request-form';
+export { DdysSearch, type DdysSearchProps } from './search';
+export { DdysSources, type DdysSourcesProps } from './sources';
+export { DdysView, type DdysViewProps } from './view';

package/src/components/movie-detail.tsx

@@ -0,0 +1,40 @@
+import type { DdysDisplayOptions, DdysItem, DdysResource } from '../types/ddys';
+import { DdysCard } from './card';
+import { DdysGrid } from './grid';
+import { DdysSources } from './sources';
+import { itemSummary } from './utils';
+
+export interface DdysMovieDetailProps {
+  movie: DdysItem;
+  display?: DdysDisplayOptions;
+  siteBaseUrl?: string;
+}
+
+export function DdysMovieDetail({ movie, display, siteBaseUrl }: DdysMovieDetailProps) {
+  const summary = itemSummary(movie);
+  const related = Array.isArray(movie.movies) ? movie.movies as DdysItem[] : [];
+  const groups = sourceGroups(movie);
+
+  return (
+    <div className="ddys-next ddys-next-detail">
+      <DdysCard item={movie} display={display} siteBaseUrl={siteBaseUrl} />
+      {summary ? <div className="ddys-next-description">{summary}</div> : null}
+      {Object.keys(groups).length ? <DdysSources groups={groups} /> : null}
+      {related.length ? (
+        <section className="ddys-next-related">
+          <h3>Related</h3>
+          <DdysGrid items={related} display={display} siteBaseUrl={siteBaseUrl} />
+        </section>
+      ) : null}
+    </div>
+  );
+}
+
+function sourceGroups(movie: DdysItem): Record<string, DdysResource[]> {
+  const groups: Record<string, DdysResource[]> = {};
+  if (Array.isArray(movie.resources)) groups.Resources = movie.resources as DdysResource[];
+  if (Array.isArray(movie.sources)) groups.Sources = movie.sources as DdysResource[];
+  if (Array.isArray(movie.online)) groups.Online = movie.online as DdysResource[];
+  if (Array.isArray(movie.download)) groups.Download = movie.download as DdysResource[];
+  return groups;
+}