@ddysiodev/js-sdk

DDYS JavaScript SDK

English | 简体中文

Official JavaScript SDK for the DDYS API.

Official website: DDYS

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

npm install @ddysiodev/js-sdk

CDN URLs:

https://cdn.jsdelivr.net/npm/@ddysiodev/js-sdk/dist/index.js
https://unpkg.com/@ddysiodev/js-sdk/dist/index.js

Public publishing:

npm publish --access public

Quick Start

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:

https://ddys.io/user/profile

Use the key on the server side or inside your own Worker/API route:

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);

Public display features do not require an API key. For write endpoints, configure the key on your server or Worker.

Custom API Base URL

Use baseUrl when your site routes requests through a cache proxy:

const ddys = createDdysClient({
  baseUrl: 'https://example.com/ddys-api'
});

API Methods

Movies

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

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

await ddys.dictionaries.types();
await ddys.dictionaries.genres();
await ddys.dictionaries.regions();

Collections, Shares, Requests, Activities

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

await ddys.users.profile('diduan');
await ddys.me();

Comments, Reports, Follow

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:

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.

const envelope = await ddys.request('/movies', {
  query: { page: 1, per_page: 3 }
});

console.log(envelope.success, envelope.data, envelope.meta);

Error Handling

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:

const ddys = createDdysClient({ fetch: customFetch });

Development

This project intentionally has no runtime dependencies and can build/test with Node only.

node scripts/build.mjs
node --test test/*.test.mjs

When npm is available:

npm test

Live smoke tests are opt-in:

DDYS_LIVE_TEST=1 node test/live-smoke.mjs

Authenticated live smoke tests also need:

DDYS_API_KEY=ddys_xxx