@zenalexa/unicli 0.220.0 → 0.220.1

package/src/adapters/bangumi/web.ts

@@ -0,0 +1,295 @@
+/**
+ * @owner   src/adapters/bangumi/web.ts
+ * @does    Register Bangumi public search/detail commands for anime, books, games, subjects, and characters.
+ * @needs   Bangumi public REST/search endpoints and user-agent policy.
+ * @feeds   Chinese/Japanese ACG title, character, and visual-novel discovery.
+ * @breaks  Bangumi legacy search endpoint or v0 subject/character schema changes can block lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const API = "https://api.bgm.tv";
+
+function str(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function required(value: unknown, label: string): string {
+  const text = str(value).trim();
+  if (!text) throw new Error(`bangumi ${label} cannot be empty.`);
+  return text;
+}
+
+function requireLimit(value: unknown): number {
+  if (value === undefined || value === null || value === "") return 10;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 50) {
+    throw new Error("bangumi limit must be an integer in [1, 50].");
+  }
+  return n;
+}
+
+function optionalYear(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1900 || n > 2100) {
+    throw new Error("bangumi year must be an integer in [1900, 2100].");
+  }
+  return n;
+}
+
+const TYPE_CODES: Record<string, number> = {
+  book: 1,
+  anime: 2,
+  music: 3,
+  game: 4,
+  real: 6,
+};
+const SORTS = new Set(["match", "rank", "score", "heat"]);
+
+function normalizeSort(value: unknown): string {
+  const sort = str(value || "match")
+    .trim()
+    .toLowerCase();
+  if (!SORTS.has(sort)) {
+    throw new Error("bangumi sort must be one of: match, rank, score, heat.");
+  }
+  return sort;
+}
+
+async function getJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok)
+    throw new Error(`bangumi request failed with HTTP ${response.status}.`);
+  return response.json();
+}
+
+async function postJson(url: string, body: unknown): Promise<unknown> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok)
+    throw new Error(`bangumi request failed with HTTP ${response.status}.`);
+  return response.json();
+}
+
+export function mapBangumiSubjects(rows: unknown[]): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const rating = item.rating as Record<string, unknown> | undefined;
+    const images = item.images as Record<string, unknown> | undefined;
+    return {
+      rank: index + 1,
+      id: item.id,
+      type: item.type,
+      name: str(item.name),
+      name_cn: str(item.name_cn),
+      date: str(item.air_date ?? item.date),
+      score: rating?.score ?? null,
+      rank_site: item.rank ?? null,
+      summary: str(item.summary).slice(0, 500),
+      image: str(images?.common),
+      url: str(item.url) || `https://bgm.tv/subject/${item.id}`,
+    };
+  });
+}
+
+export function mapBangumiSubject(
+  item: Record<string, unknown>,
+): Record<string, unknown> {
+  const rating = item.rating as Record<string, unknown> | undefined;
+  const images = item.images as Record<string, unknown> | undefined;
+  return {
+    id: item.id,
+    type: item.type,
+    name: str(item.name),
+    name_cn: str(item.name_cn),
+    platform: str(item.platform),
+    date: str(item.date),
+    score: rating?.score ?? null,
+    total_votes: rating?.total ?? null,
+    rank_site: item.rank ?? null,
+    summary: str(item.summary).slice(0, 1500),
+    image: str(images?.common),
+    url: `https://bgm.tv/subject/${item.id}`,
+  };
+}
+
+export function mapBangumiCharacters(
+  rows: unknown[],
+): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const stat = item.stat as Record<string, unknown> | undefined;
+    const images = item.images as Record<string, unknown> | undefined;
+    return {
+      rank: index + 1,
+      id: item.id,
+      name: str(item.name),
+      gender: str(item.gender),
+      type: item.type ?? null,
+      comments: stat?.comments ?? null,
+      collects: stat?.collects ?? null,
+      summary: str(item.summary).slice(0, 700),
+      image: str(images?.medium ?? images?.grid),
+      url: `https://bgm.tv/character/${item.id}`,
+    };
+  });
+}
+
+async function searchSubject(
+  kind: keyof typeof TYPE_CODES,
+  kwargs: Record<string, unknown>,
+) {
+  const cap = requireLimit(kwargs.limit);
+  const url = new URL(`${API}/v0/search/subjects`);
+  url.searchParams.set("limit", String(cap));
+  url.searchParams.set("offset", "0");
+  const data = (await postJson(
+    url.toString(),
+    bangumiSubjectSearchBody(kind, kwargs),
+  )) as { data?: unknown[] };
+  const rows = mapBangumiSubjects(data.data ?? []);
+  if (rows.length === 0)
+    throw new Error(
+      `No Bangumi ${kind} found for "${required(kwargs.query, "query")}".`,
+    );
+  return rows;
+}
+
+export function bangumiSubjectSearchBody(
+  kind: keyof typeof TYPE_CODES,
+  kwargs: Record<string, unknown>,
+): Record<string, unknown> {
+  const year = optionalYear(kwargs.year);
+  const sort = normalizeSort(kwargs.sort);
+  const filter: Record<string, unknown> = { type: [TYPE_CODES[kind]] };
+  if (year !== undefined) {
+    filter.air_date = [`>=${year}-01-01`, `<${year + 1}-01-01`];
+  }
+  return {
+    keyword: required(kwargs.query, "query"),
+    ...(sort === "match" ? {} : { sort }),
+    filter,
+  };
+}
+
+async function searchCharacters(kwargs: Record<string, unknown>) {
+  const query = required(kwargs.query, "query");
+  const cap = requireLimit(kwargs.limit);
+  const url = new URL(`${API}/v0/search/characters`);
+  url.searchParams.set("limit", String(cap));
+  const data = (await postJson(url.toString(), {
+    keyword: query,
+    filter: {},
+  })) as { data?: unknown[] };
+  const rows = mapBangumiCharacters(data.data ?? []);
+  if (rows.length === 0)
+    throw new Error(`No Bangumi characters found for "${query}".`);
+  return rows;
+}
+
+const SEARCH_ARGS = [
+  { name: "query", type: "str" as const, required: true, positional: true },
+  { name: "limit", type: "int" as const, default: 10 },
+  { name: "year", type: "int" as const },
+  {
+    name: "sort",
+    type: "str" as const,
+    default: "match",
+    choices: ["match", "rank", "score", "heat"],
+    description: "match, rank, score, heat",
+  },
+];
+const CHARACTER_ARGS = SEARCH_ARGS.filter(
+  (arg) => arg.name === "query" || arg.name === "limit",
+);
+const SUBJECT_COLUMNS = [
+  "rank",
+  "id",
+  "type",
+  "name",
+  "name_cn",
+  "date",
+  "score",
+  "rank_site",
+  "url",
+];
+const CHARACTER_COLUMNS = [
+  "rank",
+  "id",
+  "name",
+  "gender",
+  "comments",
+  "collects",
+  "summary",
+  "url",
+];
+
+for (const name of ["anime", "book", "game"] as const) {
+  cli({
+    site: "bangumi",
+    name,
+    description: `Search Bangumi ${name} subjects by Japanese title, Chinese title, romaji, or alias`,
+    domain: "bgm.tv",
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: SEARCH_ARGS,
+    columns: SUBJECT_COLUMNS,
+    func: async (_page, kwargs) => searchSubject(name, kwargs),
+  });
+}
+
+cli({
+  site: "bangumi",
+  name: "characters",
+  description:
+    "Search Bangumi characters by Japanese name, Chinese name, romaji, or alias",
+  domain: "bgm.tv",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: CHARACTER_ARGS,
+  columns: CHARACTER_COLUMNS,
+  func: async (_page, kwargs) => searchCharacters(kwargs),
+});
+
+cli({
+  site: "bangumi",
+  name: "subject",
+  description: "Get Bangumi subject details by subject id",
+  domain: "bgm.tv",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [{ name: "id", type: "str", required: true, positional: true }],
+  columns: [
+    "id",
+    "type",
+    "name",
+    "name_cn",
+    "platform",
+    "date",
+    "score",
+    "rank_site",
+    "summary",
+    "url",
+  ],
+  func: async (_page, kwargs) => [
+    mapBangumiSubject(
+      (await getJson(
+        `${API}/v0/subjects/${required(kwargs.id, "id")}`,
+      )) as Record<string, unknown>,
+    ),
+  ],
+});

package/src/adapters/danbooru/artists.yaml

@@ -0,0 +1,44 @@
+site: danbooru
+name: artists
+description: Search Danbooru artist records
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Artist name
+  limit:
+    type: int
+    default: 20
+    description: Number of artists to return
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/artists.json"
+      params:
+        "search[name]": "${{ args.query }}"
+        limit: "${{ args.limit }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      name: "${{ item.name }}"
+      group_name: "${{ item.group_name }}"
+      other_names: "${{ Array.isArray(item.other_names) ? item.other_names.join(', ') : '' }}"
+      is_banned: "${{ item.is_banned }}"
+      is_deleted: "${{ item.is_deleted }}"
+      url: "${{ 'https://danbooru.donmai.us/artists/' + item.id }}"
+
+columns: [rank, id, name, group_name, other_names, is_banned, is_deleted, url]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/danbooru/comments.yaml

@@ -0,0 +1,45 @@
+site: danbooru
+name: comments
+description: List Danbooru comments for a post
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  post_id:
+    type: str
+    required: true
+    positional: true
+    description: Danbooru post ID
+    x-unicli-kind: id
+  limit:
+    type: int
+    default: 20
+    description: Number of comments to return
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/comments.json"
+      params:
+        "search[post_id]": "${{ args.post_id }}"
+        limit: "${{ args.limit }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      post_id: "${{ item.post_id }}"
+      creator_id: "${{ item.creator_id }}"
+      score: "${{ item.score }}"
+      body: "${{ String(item.body || '').replace(/\\s+/g, ' ').trim() }}"
+      created_at: "${{ item.created_at }}"
+      is_deleted: "${{ item.is_deleted }}"
+
+columns: [rank, id, post_id, creator_id, score, body, created_at, is_deleted]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/danbooru/detail.yaml

@@ -0,0 +1,78 @@
+site: danbooru
+name: detail
+description: Get Danbooru post details by ID
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+    description: Danbooru post ID
+    x-unicli-kind: id
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/posts/${{ args.id }}.json"
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      up_score: "${{ item.up_score }}"
+      down_score: "${{ item.down_score }}"
+      fav_count: "${{ item.fav_count }}"
+      file_ext: "${{ item.file_ext }}"
+      file_size: "${{ item.file_size }}"
+      image_width: "${{ item.image_width }}"
+      image_height: "${{ item.image_height }}"
+      artist_tags: "${{ item.tag_string_artist }}"
+      character_tags: "${{ item.tag_string_character }}"
+      copyright_tags: "${{ item.tag_string_copyright }}"
+      general_tags: "${{ item.tag_string_general }}"
+      meta_tags: "${{ item.tag_string_meta }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_file_url }}"
+      large_url: "${{ item.large_file_url }}"
+      file_url: "${{ item.file_url }}"
+      pixiv_id: "${{ item.pixiv_id }}"
+      parent_id: "${{ item.parent_id }}"
+      has_children: "${{ item.has_children }}"
+      url: "${{ 'https://danbooru.donmai.us/posts/' + item.id }}"
+
+columns:
+  [
+    id,
+    rating,
+    score,
+    up_score,
+    down_score,
+    fav_count,
+    file_ext,
+    file_size,
+    image_width,
+    image_height,
+    artist_tags,
+    character_tags,
+    copyright_tags,
+    general_tags,
+    meta_tags,
+    source,
+    preview_url,
+    large_url,
+    file_url,
+    pixiv_id,
+    parent_id,
+    has_children,
+    url,
+  ]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/danbooru/download.yaml

@@ -0,0 +1,51 @@
+site: danbooru
+name: download
+description: Download original media for a Danbooru post
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+    description: Danbooru post ID
+    x-unicli-kind: id
+  output:
+    type: str
+    default: "./danbooru-downloads"
+    description: Output directory
+    x-unicli-kind: path
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/posts/${{ args.id }}.json"
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      tags: "${{ item.tag_string }}"
+      file_ext: "${{ item.file_ext }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://danbooru.donmai.us/posts/' + item.id }}"
+
+  - assert:
+      condition: "data.length > 0 && data[0].file_url"
+      message: "Danbooru post has no public downloadable file URL."
+
+  - download:
+      url: "${{ item.file_url }}"
+      dir: "${{ args.output }}"
+      filename: "${{ item.id }}.${{ item.file_ext | default('bin') }}"
+      type: auto
+
+columns: [id, rating, tags, file_url, url, _download]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch", "http.download"]
+minimum_capability: http.download
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/danbooru/pools.yaml

@@ -0,0 +1,56 @@
+site: danbooru
+name: pools
+description: Search Danbooru pools
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Pool name wildcard query
+  limit:
+    type: int
+    default: 20
+    description: Number of pools to return
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/pools.json"
+      params:
+        "search[name_matches]": "${{ args.query }}"
+        limit: "${{ args.limit }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      name: "${{ item.name }}"
+      category: "${{ item.category }}"
+      post_count: "${{ item.post_count }}"
+      description: "${{ String(item.description || '').replace(/\\s+/g, ' ').slice(0, 250) }}"
+      is_active: "${{ item.is_active }}"
+      is_deleted: "${{ item.is_deleted }}"
+      url: "${{ 'https://danbooru.donmai.us/pools/' + item.id }}"
+
+columns:
+  [
+    rank,
+    id,
+    name,
+    category,
+    post_count,
+    description,
+    is_active,
+    is_deleted,
+    url,
+  ]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/danbooru/search.yaml

@@ -0,0 +1,69 @@
+site: danbooru
+name: search
+description: Search Danbooru posts by tag query
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  tags:
+    type: str
+    required: true
+    positional: true
+    description: Danbooru tag query, for example "landscape rating:g"
+  limit:
+    type: int
+    default: 20
+    description: Number of posts to return
+  page:
+    type: int
+    default: 1
+    description: Page number
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/posts.json"
+      params:
+        tags: "${{ args.tags }}"
+        limit: "${{ args.limit }}"
+        page: "${{ args.page }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      fav_count: "${{ item.fav_count }}"
+      file_ext: "${{ item.file_ext }}"
+      image_width: "${{ item.image_width }}"
+      image_height: "${{ item.image_height }}"
+      tags: "${{ item.tag_string }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_file_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://danbooru.donmai.us/posts/' + item.id }}"
+
+columns:
+  [
+    rank,
+    id,
+    rating,
+    score,
+    fav_count,
+    file_ext,
+    image_width,
+    image_height,
+    tags,
+    source,
+    preview_url,
+    file_url,
+    url,
+  ]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/danbooru/tags.yaml

@@ -0,0 +1,42 @@
+site: danbooru
+name: tags
+description: Search Danbooru tags
+domain: danbooru.donmai.us
+type: web-api
+strategy: public
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Tag name prefix or wildcard query
+  limit:
+    type: int
+    default: 20
+    description: Number of tags to return
+
+pipeline:
+  - fetch:
+      url: "https://danbooru.donmai.us/tags.json"
+      params:
+        "search[name_matches]": "${{ args.query }}"
+        limit: "${{ args.limit }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      name: "${{ item.name }}"
+      post_count: "${{ item.post_count }}"
+      category: "${{ item.category }}"
+      is_deprecated: "${{ item.is_deprecated }}"
+
+columns: [rank, id, name, post_count, category, is_deprecated]
+
+# schema-v2 metadata — injected by `unicli migrate schema-v2`
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2