pixivflow 2.16.0 → 2.17.0

package/node_modules/@redtidev/pixiv-client/src/app-api/illustrations.ts

@@ -0,0 +1,144 @@
+import type { Transport } from '../transport/transport';
+import type { PixivIllust, PixivTag, UgoiraMetadata, Paginated } from '../models';
+import type { IllustRankingMode, IllustSearchOptions, OnePageResult, RankingOptions, UserWorksOptions } from './options';
+
+/** Illustration endpoints of the Pixiv public App API. */
+export class IllustrationsApi {
+  constructor(private readonly transport: Transport) {}
+
+  get(id: number, signal?: AbortSignal): Promise<PixivIllust> {
+    return this.detail(id, signal);
+  }
+
+  async detail(id: number, signal?: AbortSignal): Promise<PixivIllust> {
+    const res = await this.transport.request<{ illust: PixivIllust }>(
+      `/v1/illust/detail?illust_id=${encodeURIComponent(String(id))}`,
+      { method: 'GET', signal }
+    );
+    return res.illust;
+  }
+
+  async detailWithTags(id: number, signal?: AbortSignal): Promise<{
+    illust: PixivIllust;
+    tags: PixivTag[];
+  }> {
+    const res = await this.transport.request<{ illust: PixivIllust & { tags?: PixivTag[] } }>(
+      `/v1/illust/detail?illust_id=${encodeURIComponent(String(id))}`,
+      { method: 'GET', signal }
+    );
+    const tags = res.illust.tags ?? [];
+    const { tags: _omit, ...illust } = res.illust as PixivIllust & { tags?: PixivTag[] };
+    return { illust, tags };
+  }
+
+  /** One user-works page (type=illust). Use {@link listByUser} for walking. */
+  async userWorksPage(userId: string, cursor: string | null, options: UserWorksOptions = {}): Promise<OnePageResult<PixivIllust>> {
+    let url: string;
+    if (cursor) {
+      url = cursor;
+    } else {
+      const params = new URLSearchParams({ user_id: userId, type: 'illust', filter: 'for_ios' });
+      if (options.offset) params.set('offset', String(options.offset));
+      url = `/v1/user/illusts?${params.toString()}`;
+    }
+    const res = await this.transport.request<{ illusts: PixivIllust[]; next_url?: string | null }>(url, {
+      method: 'GET',
+      signal: options.signal,
+    });
+    return { items: res.illusts ?? [], next: res.next_url ?? null };
+  }
+
+  /** User illustrations, walking next_url up to `limit` (default 30). */
+  async listByUser(userId: string, options: UserWorksOptions = {}): Promise<PixivIllust[]> {
+    const limit = options.limit ?? 30;
+    const out: PixivIllust[] = [];
+    let cursor: string | null = null;
+    do {
+      const page = await this.userWorksPage(userId, cursor, options);
+      out.push(...page.items);
+      cursor = page.next;
+      if (!page.items.length) break;
+    } while (cursor && out.length < limit);
+    return out.slice(0, limit);
+  }
+
+  async rankingPage(mode: IllustRankingMode, options: RankingOptions = {}, cursor: string | null = null): Promise<OnePageResult<PixivIllust>> {
+    let url: string;
+    if (cursor) {
+      url = cursor;
+    } else {
+      const params = new URLSearchParams({ mode, filter: 'for_ios' });
+      if (options.date) params.set('date', options.date);
+      url = `/v1/illust/ranking?${params.toString()}`;
+    }
+    const res = await this.transport.request<{ illusts: PixivIllust[]; next_url?: string | null }>(url, {
+      method: 'GET',
+      signal: options.signal,
+    });
+    return { items: res.illusts ?? [], next: res.next_url ?? null };
+  }
+
+  async ranking(mode: IllustRankingMode, options: RankingOptions = {}): Promise<PixivIllust[]> {
+    const limit = options.limit;
+    const out: PixivIllust[] = [];
+    let cursor: string | null = null;
+    do {
+      const page = await this.rankingPage(mode, options, cursor);
+      out.push(...page.items);
+      cursor = page.next;
+      if (!page.items.length) break;
+    } while (cursor && (limit === undefined || out.length < limit));
+    return limit !== undefined ? out.slice(0, limit) : out;
+  }
+
+  /** One illustration search page. PixivFlow uses this for date-aware paging. */
+  async searchPage(options: IllustSearchOptions, cursor: string | null = null): Promise<OnePageResult<PixivIllust>> {
+    let url: string;
+    if (cursor) {
+      url = cursor;
+    } else {
+      const paramsObj: Record<string, string> = {
+        word: options.word,
+        search_target: options.searchTarget ?? 'partial_match_for_tags',
+        include_translated_tag_results: options.includeTranslatedTagResults === false ? 'false' : 'true',
+      };
+      if (!options.includeR18) paramsObj.filter = 'for_ios';
+      const params = new URLSearchParams(paramsObj);
+      params.set('sort', options.sort ?? 'date_desc');
+      if (options.startDate) params.set('start_date', options.startDate);
+      if (options.endDate) params.set('end_date', options.endDate);
+      url = `/v1/search/illust?${params.toString()}`;
+    }
+    const res = await this.transport.request<{ illusts: PixivIllust[]; next_url?: string | null }>(url, {
+      method: 'GET',
+      signal: options.signal,
+    });
+    return { items: res.illusts ?? [], next: res.next_url ?? null };
+  }
+
+  /**
+   * Search illustrations, walking next_url up to `limit` (default 30).
+   * NOTE: hosts that must stop early on a date boundary or merge tag unions
+   * should call {@link searchPage} in their own loop (PixivFlow does).
+   */
+  async search(options: IllustSearchOptions): Promise<Paginated<PixivIllust>> {
+    const limit = options.limit ?? 30;
+    const out: PixivIllust[] = [];
+    let cursor: string | null = options.cursor ?? null;
+    do {
+      const page = await this.searchPage(options, cursor);
+      out.push(...page.items);
+      cursor = page.next;
+      if (!page.items.length) break;
+    } while (cursor && out.length < limit);
+    return { items: out.slice(0, limit), nextCursor: cursor };
+  }
+
+  async ugoiraMetadata(illustId: number, signal?: AbortSignal): Promise<UgoiraMetadata> {
+    const res = await this.transport.request<{ ugoira_metadata: UgoiraMetadata }>(
+      `/v1/ugoira/metadata?illust_id=${encodeURIComponent(String(illustId))}`,
+      { method: 'GET', signal }
+    );
+    return res.ugoira_metadata;
+  }
+}

package/node_modules/@redtidev/pixiv-client/src/app-api/media.ts

@@ -0,0 +1,20 @@
+import type { Transport } from '../transport/transport';
+
+/**
+ * Media (binary) fetch. The kit returns BYTES only; where to save, naming,
+ * unzip/ugoira→GIF conversion and download history are host concerns.
+ */
+export class MediaApi {
+  constructor(private readonly transport: Transport) {}
+
+  /** Download a media URL (images, ugoira zips) as ArrayBuffer. */
+  fetch(url: string, options?: { referer?: string; timeoutMs?: number; signal?: AbortSignal }): Promise<ArrayBuffer> {
+    return this.transport.fetchBinary(url, {
+      method: 'GET',
+      headers: { Referer: options?.referer ?? 'https://app-api.pixiv.net/' },
+      skipAuth: true,
+      timeoutMs: options?.timeoutMs,
+      signal: options?.signal,
+    });
+  }
+}

package/node_modules/@redtidev/pixiv-client/src/app-api/novels.ts

@@ -0,0 +1,269 @@
+import { PixivApiError, PixivNetworkError, PixivNotFoundError } from '../errors/errors';
+import type { Transport } from '../transport/transport';
+import type { PixivNovel, PixivNovelTextResponse, PixivUser, PixivTag, Paginated } from '../models';
+import type { NovelRankingMode, NovelSearchOptions, OnePageResult, RankingOptions, UserWorksOptions } from './options';
+
+const BROWSER_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126 Safari/537.36';
+
+/** Novel endpoints of the Pixiv public App API (+ required webview fallback). */
+export class NovelsApi {
+  constructor(private readonly transport: Transport) {}
+
+  /** Novel detail (v2 endpoint). */
+  async get(id: number, signal?: AbortSignal): Promise<PixivNovel> {
+    return this.detail(id, signal);
+  }
+
+  async detail(id: number, signal?: AbortSignal): Promise<PixivNovel> {
+    const res = await this.transport.request<{ novel: PixivNovel }>(
+      `/v2/novel/detail?novel_id=${encodeURIComponent(String(id))}`,
+      { method: 'GET', signal }
+    );
+    return res.novel;
+  }
+
+  /**
+   * Detail + tags. v2 is primary; v1 is a CAPABILITY fallback for works whose
+   * v2 endpoint is missing (404/'end-point' responses), not a 429 workaround.
+   */
+  async detailWithTags(id: number, signal?: AbortSignal): Promise<{ novel: PixivNovel; tags: PixivTag[] }> {
+    try {
+      const res = await this.transport.request<{ novel: PixivNovel & { tags?: PixivTag[] } }>(
+        `/v2/novel/detail?novel_id=${encodeURIComponent(String(id))}`,
+        { method: 'GET', signal }
+      );
+      return this.splitTags(res.novel);
+    } catch (e) {
+      if (!this.isMissingEndpoint(e)) throw e;
+      const res = await this.transport.request<{ novel: PixivNovel & { tags?: PixivTag[] } }>(
+        `/v1/novel/detail?novel_id=${encodeURIComponent(String(id))}`,
+        { method: 'GET', signal }
+      );
+      return this.splitTags(res.novel);
+    }
+  }
+
+  /** v2 with v1 capability fallback (matches legacy behavior). */
+  async detailCompatible(id: number, signal?: AbortSignal): Promise<PixivNovel> {
+    try {
+      return await this.detail(id, signal);
+    } catch (e) {
+      if (!this.isMissingEndpoint(e)) throw e;
+      const res = await this.transport.request<{ novel: PixivNovel }>(
+        `/v1/novel/detail?novel_id=${encodeURIComponent(String(id))}`,
+        { method: 'GET', signal }
+      );
+      return res.novel;
+    }
+  }
+
+  async userWorksPage(userId: string, cursor: string | null, options: UserWorksOptions = {}): Promise<OnePageResult<PixivNovel>> {
+    let url: string;
+    if (cursor) {
+      url = cursor;
+    } else {
+      const params = new URLSearchParams({ user_id: userId, filter: 'for_ios' });
+      if (options.offset) params.set('offset', String(options.offset));
+      url = `/v1/user/novels?${params.toString()}`;
+    }
+    const res = await this.transport.request<{ novels: PixivNovel[]; next_url?: string | null }>(url, {
+      method: 'GET',
+      signal: options.signal,
+    });
+    return { items: res.novels ?? [], next: res.next_url ?? null };
+  }
+
+  async listByUser(userId: string, options: UserWorksOptions = {}): Promise<PixivNovel[]> {
+    const limit = options.limit ?? 30;
+    const out: PixivNovel[] = [];
+    let cursor: string | null = null;
+    do {
+      const page = await this.userWorksPage(userId, cursor, options);
+      out.push(...page.items.slice(0, limit - out.length));
+      cursor = page.next;
+      if (!page.items.length) break;
+    } while (cursor && out.length < limit);
+    return out.slice(0, limit);
+  }
+
+  async rankingPage(mode: NovelRankingMode, options: RankingOptions = {}, cursor: string | null = null): Promise<OnePageResult<PixivNovel>> {
+    let url: string;
+    if (cursor) {
+      url = cursor;
+    } else {
+      const params = new URLSearchParams({ mode });
+      if (options.date) params.set('date', options.date);
+      url = `/v1/novel/ranking?${params.toString()}`;
+    }
+    const res = await this.transport.request<{ novels: PixivNovel[]; next_url?: string | null }>(url, {
+      method: 'GET',
+      signal: options.signal,
+    });
+    return { items: res.novels ?? [], next: res.next_url ?? null };
+  }
+
+  async ranking(mode: NovelRankingMode, options: RankingOptions = {}): Promise<PixivNovel[]> {
+    const limit = options.limit;
+    const out: PixivNovel[] = [];
+    let cursor: string | null = null;
+    do {
+      const page = await this.rankingPage(mode, options, cursor);
+      out.push(...page.items);
+      cursor = page.next;
+      if (!page.items.length) break;
+    } while (cursor && (limit === undefined || out.length < limit));
+    return limit !== undefined ? out.slice(0, limit) : out;
+  }
+
+  async searchPage(options: NovelSearchOptions, cursor: string | null = null): Promise<OnePageResult<PixivNovel>> {
+    let url: string;
+    if (cursor) {
+      url = cursor;
+    } else {
+      const paramsObj: Record<string, string> = {
+        word: options.word,
+        search_target: options.searchTarget ?? 'partial_match_for_tags',
+      };
+      if (!options.includeR18) paramsObj.filter = 'for_ios';
+      const params = new URLSearchParams(paramsObj);
+      params.set('sort', options.sort ?? 'date_desc');
+      if (options.startDate) params.set('start_date', options.startDate);
+      if (options.endDate) params.set('end_date', options.endDate);
+      url = `/v1/search/novel?${params.toString()}`;
+    }
+    const res = await this.transport.request<{ novels: PixivNovel[]; next_url?: string | null }>(url, {
+      method: 'GET',
+      signal: options.signal,
+    });
+    return { items: res.novels ?? [], next: res.next_url ?? null };
+  }
+
+  async search(options: NovelSearchOptions): Promise<Paginated<PixivNovel>> {
+    const limit = options.limit ?? 30;
+    const out: PixivNovel[] = [];
+    let cursor: string | null = options.cursor ?? null;
+    do {
+      const page = await this.searchPage(options, cursor);
+      out.push(...page.items);
+      cursor = page.next;
+      if (!page.items.length) break;
+    } while (cursor && out.length < limit);
+    return { items: out.slice(0, limit), nextCursor: cursor };
+  }
+
+  async listSeries(seriesId: number, signal?: AbortSignal): Promise<PixivNovel[]> {
+    type SeriesEntry = { id: number; title: string; user: PixivUser; create_date: string };
+    type SeriesResponse = {
+      novel_series_detail?: { series_content?: SeriesEntry[] };
+      series_content?: SeriesEntry[];
+      novels?: PixivNovel[];
+      next_url?: string | null;
+    };
+    let currentUrl: string = `/v1/novel/series?series_id=${encodeURIComponent(String(seriesId))}`;
+    const out: PixivNovel[] = [];
+    for (;;) {
+      const res: SeriesResponse = await this.transport.request<SeriesResponse>(currentUrl, { method: 'GET', signal });
+
+      const content = res.novel_series_detail?.series_content ?? res.series_content;
+      if (content) {
+        for (const c of content) out.push({ id: c.id, title: c.title, user: c.user, create_date: c.create_date });
+      } else if (Array.isArray(res.novels)) {
+        out.push(...res.novels);
+      } else {
+        throw new PixivApiError('Unexpected response structure from novel series API.', {
+          endpoint: currentUrl,
+        });
+      }
+      if (!res.next_url) break;
+      currentUrl = res.next_url;
+    }
+    return out;
+  }
+
+  /**
+   * Novel text with the proven three-tier fallback chain:
+   * webview v2 (gallery-dl style) -> legacy app-api v1 -> www.pixiv.net ajax.
+   * Only a genuinely non-empty body counts as success.
+   * These are ENDPOINT CAPABILITY fallbacks, never 429 rotation.
+   */
+  async text(novelId: number, options: { browserUserAgent?: string; signal?: AbortSignal } = {}): Promise<PixivNovelTextResponse> {
+    const failures: string[] = [];
+
+    try {
+      const html = await this.transport.requestText(
+        `/webview/v2/novel?id=${encodeURIComponent(String(novelId))}&viewer_version=20221031_ai`,
+        { method: 'GET', signal: options.signal }
+      );
+      const marker = 'novel: ';
+      const start = html.indexOf(marker);
+      if (start !== -1) {
+        const from = start + marker.length;
+        const end = html.indexOf(',\n', from);
+        if (end !== -1) {
+          const parsed = JSON.parse(html.slice(from, end)) as { text?: unknown };
+          const text = this.nonEmptyText(parsed?.text);
+          if (text) return { novel_text: text };
+        }
+      }
+      failures.push('webview returned no non-empty novel text');
+    } catch (error) {
+      failures.push(`webview (${this.messageOf(error)})`);
+    }
+
+    try {
+      const res = await this.transport.request<PixivNovelTextResponse>(
+        `/v1/novel/text?novel_id=${encodeURIComponent(String(novelId))}`,
+        { method: 'GET', signal: options.signal }
+      );
+      const text = this.nonEmptyText(res?.novel_text);
+      if (text) return { novel_text: text };
+      failures.push('app-api returned no non-empty novel_text');
+    } catch (error) {
+      failures.push(`app-api (${this.messageOf(error)})`);
+    }
+
+    // www.pixiv.net rejects the App Bearer token -> skipAuth + browser headers.
+    const ajaxUrl = `https://www.pixiv.net/ajax/novel/${novelId}`;
+    try {
+      const resp = await this.transport.request<{ error?: boolean; message?: string; body?: { content?: unknown } }>(ajaxUrl, {
+        method: 'GET',
+        headers: {
+          Referer: 'https://www.pixiv.net/',
+          'User-Agent': options.browserUserAgent ?? BROWSER_UA,
+        },
+        skipAuth: true,
+        skipAppHeaders: true,
+        signal: options.signal,
+      });
+      if (resp?.error) {
+        throw new PixivNetworkError(`ajax endpoint returned error: ${resp.message || 'unknown'}`, { endpoint: ajaxUrl });
+      }
+      const text = this.nonEmptyText(resp?.body?.content);
+      if (text) return { novel_text: text };
+      failures.push('web ajax returned no non-empty content');
+    } catch (error) {
+      failures.push(`web ajax (${this.messageOf(error)})`);
+    }
+
+    throw new PixivApiError(`novel text failed for ${novelId}: ${failures.join('; ')}`, { endpoint: ajaxUrl });
+  }
+
+  private splitTags(novel: PixivNovel & { tags?: PixivTag[] }): { novel: PixivNovel; tags: PixivTag[] } {
+    const tags = novel.tags ?? [];
+    const { tags: _omit, ...rest } = novel;
+    return { novel: rest as PixivNovel, tags };
+  }
+
+  private isMissingEndpoint(e: unknown): boolean {
+    return e instanceof PixivNotFoundError || (e instanceof Error && /end-point/.test(e.message));
+  }
+
+  private nonEmptyText(value: unknown): string | null {
+    return typeof value === 'string' && value.trim() ? value : null;
+  }
+
+  private messageOf(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+  }
+}

package/node_modules/@redtidev/pixiv-client/src/app-api/options.ts

@@ -0,0 +1,73 @@
+/**
+ * Kit-native query DTOs. These are Pixiv protocol parameters ONLY — no host
+ * application config (TargetConfig/StandaloneConfig) may appear here.
+ */
+
+export type SearchSort = 'date_desc' | 'date_asc' | 'popular_desc';
+export type SearchTarget =
+  | 'partial_match_for_tags'
+  | 'exact_match_for_tags'
+  | 'title_and_caption';
+
+export interface IllustSearchOptions {
+  word: string;
+  sort?: SearchSort;
+  searchTarget?: SearchTarget;
+  /** Include R-18 works (omit Pixiv's filter=for_ios). Default false. */
+  includeR18?: boolean;
+  includeTranslatedTagResults?: boolean;
+  /** YYYY-MM-DD, sent to the endpoint when present. */
+  startDate?: string;
+  endDate?: string;
+  /** Max items to collect through next_url pages. Default 30 (one page). */
+  limit?: number;
+  /** Start from a Pixiv next_url cursor. */
+  cursor?: string | null;
+  signal?: AbortSignal;
+}
+
+export interface NovelSearchOptions extends IllustSearchOptions {}
+
+export type IllustRankingMode =
+  | 'day'
+  | 'week'
+  | 'month'
+  | 'day_male'
+  | 'day_female'
+  | 'week_original'
+  | 'week_rookie'
+  | 'day_r18'
+  | 'day_male_r18'
+  | 'day_female_r18'
+  | 'week_r18'
+  | 'week_r18g';
+
+export type NovelRankingMode =
+  | 'day'
+  | 'week'
+  | 'month'
+  | 'day_male'
+  | 'day_female'
+  | 'day_r18'
+  | 'day_male_r18'
+  | 'day_female_r18'
+  | 'week_r18'
+  | 'week_r18g';
+
+export interface RankingOptions {
+  date?: string;
+  limit?: number;
+  signal?: AbortSignal;
+}
+
+export interface UserWorksOptions {
+  offset?: number;
+  limit?: number;
+  signal?: AbortSignal;
+}
+
+export interface OnePageResult<T> {
+  items: T[];
+  /** Pixiv next_url (opaque cursor), null on the last page. */
+  next: string | null;
+}

package/node_modules/@redtidev/pixiv-client/src/app-api/tags.ts

@@ -0,0 +1,21 @@
+import type { Transport } from '../transport/transport';
+import type { PixivTag } from '../models';
+
+/** Tag autocomplete endpoint used for tag discovery. */
+export class TagsApi {
+  constructor(private readonly transport: Transport) {}
+
+  async autocomplete(word: string, signal?: AbortSignal): Promise<PixivTag[]> {
+    const params = new URLSearchParams({
+      word,
+      merge_plain_keyword_results: 'true',
+    });
+    const response = await this.transport.request<{
+      tags?: PixivTag[];
+      search_auto_complete_keywords?: string[];
+    }>(`/v2/search/autocomplete?${params.toString()}`, { method: 'GET', signal });
+
+    if (Array.isArray(response.tags)) return response.tags;
+    return (response.search_auto_complete_keywords ?? []).map((name) => ({ name }));
+  }
+}

package/node_modules/@redtidev/pixiv-client/src/app-api/users.ts

@@ -0,0 +1,22 @@
+import type { Transport } from '../transport/transport';
+import type { PixivUser } from '../models';
+
+/** User endpoints (App API). */
+export class UsersApi {
+  constructor(private readonly transport: Transport) {}
+
+  /**
+   * Public profile of one user.
+   * NOTE: `/v1/user/profile` (the old "current user") endpoint was removed by
+   * Pixiv and now always answers 404 "Specified end-point doesn't exist"; the
+   * App API only exposes per-user detail, which is what this wraps.
+   */
+  async user(userId: string | number, options: { signal?: AbortSignal } = {}): Promise<PixivUser> {
+    const params = new URLSearchParams({ user_id: String(userId), filter: 'for_ios' });
+    const response = await this.transport.request<{ user: PixivUser }>(
+      `/v1/user/detail?${params.toString()}`,
+      { method: 'GET', signal: options.signal }
+    );
+    return response.user;
+  }
+}

package/node_modules/@redtidev/pixiv-client/src/auth/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Authentication ports. The kit only CONSUMES access tokens; it never knows
+ * how the host obtained them (OAuth PKCE browser login, puppeteer, a python
+ * helper, a refresh-token flow, a static test token, ...).
+ */
+
+/** Minimal port: return a currently-valid Bearer access token. */
+export interface AccessTokenProvider {
+  getAccessToken(signal?: AbortSignal): Promise<string>;
+}
+
+/**
+ * Optional capability: when a request comes back 401 the transport asks the
+ * provider to refresh once and then retries the original request. Providers
+ * that cannot refresh simply implement {@link AccessTokenProvider}.
+ */
+export interface RefreshableAccessTokenProvider extends AccessTokenProvider {
+  refreshAccessToken(signal?: AbortSignal): Promise<string>;
+}
+
+export function isRefreshable(
+  provider: AccessTokenProvider
+): provider is RefreshableAccessTokenProvider {
+  return typeof (provider as Partial<RefreshableAccessTokenProvider>).refreshAccessToken === 'function';
+}
+
+/** Token provider for tests / simple embeddings: always returns one token. */
+export class StaticTokenProvider implements AccessTokenProvider {
+  constructor(private readonly token: string) {}
+  async getAccessToken(): Promise<string> {
+    return this.token;
+  }
+}

package/node_modules/@redtidev/pixiv-client/src/client.ts

@@ -0,0 +1,105 @@
+import type { AccessTokenProvider } from './auth/types';
+import { StaticTokenProvider } from './auth/types';
+import { silentLogger, type KitLogger } from './logger';
+import { RateLimitGate } from './rate-limit/RateLimitGate';
+import { Transport } from './transport/transport';
+import { IllustrationsApi } from './app-api/illustrations';
+import { NovelsApi } from './app-api/novels';
+import { TagsApi } from './app-api/tags';
+import { MediaApi } from './app-api/media';
+import { UsersApi } from './app-api/users';
+import type {
+  KitEventListener,
+  PixivClientOptions,
+  ProxyOptions,
+  RateLimitOptions,
+  RateLimitStatus,
+} from './types';
+
+/**
+ * Single public entry point of the kit.
+ *
+ *   const pixiv = createPixivClient({ auth: new StaticTokenProvider(t) });
+ *   const illust = await pixiv.illustrations.get(123);
+ *
+ * The client knows Pixiv only: no host config, no SQLite, no puppeteer.
+ */
+export class PixivClient {
+  readonly illustrations: IllustrationsApi;
+  readonly novels: NovelsApi;
+  readonly tags: TagsApi;
+  readonly media: MediaApi;
+  readonly users: UsersApi;
+  private readonly gate: RateLimitGate;
+  private readonly logger: KitLogger;
+
+  constructor(options: PixivClientOptions) {
+    this.logger = options.logger ?? silentLogger;
+    const emit = options.onEvent;
+    // A host-injected sleep (tests, custom schedulers) must drive BOTH the
+    // gate's pacing waits and the transport's retry waits; otherwise a host
+    // that injects one still gets real timers from the other.
+    this.gate = new RateLimitGate(
+      { sleep: options.sleep, ...(options.rateLimit ?? {}) },
+      this.logger,
+      emit
+    );
+
+    const proxy = options.proxy ? normalizeProxy(options.proxy) : undefined;
+
+    const transport = new Transport({
+      baseUrl: options.baseUrl ?? 'https://app-api.pixiv.net',
+      userAgent: options.userAgent,
+      timeoutMs: options.timeoutMs ?? 30_000,
+      retries: options.retries ?? 2,
+      proxy,
+      auth: options.auth,
+      gate: this.gate,
+      logger: this.logger,
+      emit,
+      fetchImpl: options.fetchImpl,
+      coalesce: options.coalesceRequests ?? true,
+      sleep: options.sleep,
+    });
+
+    this.illustrations = new IllustrationsApi(transport);
+    this.novels = new NovelsApi(transport);
+    this.tags = new TagsApi(transport);
+    this.media = new MediaApi(transport);
+    this.users = new UsersApi(transport);
+  }
+
+  /** Health view for host doctor/health/monitor UIs (no credentials). */
+  getRateLimitStatus(): Promise<RateLimitStatus> {
+    return this.gate.getStatus();
+  }
+
+  /** Advanced: the shared gate, for hosts that need to inject state/inspect. */
+  getRateLimitGate(): RateLimitGate {
+    return this.gate;
+  }
+}
+
+function normalizeProxy(proxy: ProxyOptions): ProxyOptions {
+  return { protocol: (proxy.protocol ?? 'http').toLowerCase() as ProxyOptions['protocol'], ...proxy };
+}
+
+export interface CreatePixivClientOptions extends PixivClientOptions {}
+
+/** Convenience factory (also accepts a raw token string). */
+export function createPixivClient(
+  options: PixivClientOptions | { token: string; userAgent?: string; proxy?: ProxyOptions; rateLimit?: RateLimitOptions; logger?: KitLogger; onEvent?: KitEventListener }
+): PixivClient {
+  if ('token' in options) {
+    const auth: AccessTokenProvider = new StaticTokenProvider(options.token);
+    return new PixivClient({
+      auth,
+      userAgent: options.userAgent,
+      proxy: options.proxy,
+      rateLimit: options.rateLimit,
+      logger: options.logger,
+      onEvent: options.onEvent,
+    });
+  }
+  return new PixivClient(options);
+}