pixivflow 2.16.0 → 2.17.0

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

@@ -0,0 +1,180 @@
+/**
+ * Typed error hierarchy for the Pixiv Client Kit.
+ *
+ * Callers classify failures structurally (instanceof + fields), never by
+ * matching strings in error messages:
+ *
+ *   try {
+ *     await pixiv.illustrations.get(123);
+ *   } catch (e) {
+ *     if (e instanceof PixivRateLimitError) await sleep(e.retryAfterMs);
+ *     else if (e instanceof PixivNotFoundError) skip();
+ *     else throw e;
+ *   }
+ *
+ * Compatibility: every error exposes `statusCode` / `code` / `isRateLimit` /
+ * `waitTime` getters, so host code written against the legacy PixivFlow
+ * `NetworkError(message, url, cause, metadata)` shape keeps working.
+ */
+
+export interface PixivErrorDetails {
+  /** HTTP status code, when the failure came from an HTTP response. */
+  status?: number;
+  /** Machine-readable code (e.g. 'rate_limited', 'timeout'). */
+  code?: string;
+  /** Whether the operation may succeed if retried later. */
+  retryable?: boolean;
+  /** Delay the caller should wait before retrying, when known (ms). */
+  retryAfterMs?: number;
+  /** Endpoint / absolute URL the request targeted (never contains secrets). */
+  endpoint?: string;
+  /** Original underlying error. */
+  cause?: unknown;
+}
+
+export class PixivError extends Error {
+  readonly status?: number;
+  readonly code?: string;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number;
+  readonly endpoint?: string;
+  override readonly cause?: unknown;
+
+  constructor(message: string, details: PixivErrorDetails = {}) {
+    super(message);
+    this.name = 'PixivError';
+    this.status = details.status;
+    this.code = details.code;
+    this.retryable = details.retryable ?? false;
+    this.retryAfterMs = details.retryAfterMs;
+    this.endpoint = details.endpoint;
+    if (details.cause !== undefined) this.cause = details.cause;
+    if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
+  }
+
+  // --- legacy PixivFlow compatibility accessors -----------------------------
+  /** @deprecated use `status`. Kept so legacy `NetworkError` consumers compile. */
+  get statusCode(): number | undefined {
+    return this.status;
+  }
+  /** @deprecated use `endpoint`. */
+  get url(): string | undefined {
+    return this.endpoint;
+  }
+  /** @deprecated use `instanceof PixivRateLimitError`. */
+  get isRateLimit(): boolean {
+    return this instanceof PixivRateLimitError;
+  }
+  /** @deprecated use `retryAfterMs`. */
+  get waitTime(): number | undefined {
+    return this.retryAfterMs;
+  }
+}
+
+/** Network-level failure (DNS, reset, proxy, timeout): no HTTP response. */
+export class PixivNetworkError extends PixivError {
+  constructor(message: string, details: PixivErrorDetails = {}) {
+    super(message, { retryable: true, code: 'network_error', ...details });
+    this.name = 'PixivNetworkError';
+  }
+}
+
+/** Request timed out (our AbortController, not an HTTP response). */
+export class PixivTimeoutError extends PixivNetworkError {
+  constructor(message: string, details: PixivErrorDetails = {}) {
+    super(message, { code: 'timeout', ...details });
+    this.name = 'PixivTimeoutError';
+  }
+}
+
+/** Non-2xx HTTP response base. */
+export class PixivHttpError extends PixivError {
+  /** Response body text, truncated (may be empty). */
+  readonly body?: string;
+  constructor(message: string, details: PixivErrorDetails & { body?: string } = {}) {
+    super(message, { code: `http_${details.status ?? 'unknown'}`, ...details });
+    this.name = 'PixivHttpError';
+    this.body = details.body;
+  }
+}
+
+/** 401: access token missing/expired and refresh did not recover it. */
+export class PixivAuthenticationError extends PixivHttpError {
+  constructor(message: string, details: PixivErrorDetails & { body?: string } = {}) {
+    super(message, { status: 401, code: 'unauthorized', retryable: false, ...details });
+    this.name = 'PixivAuthenticationError';
+  }
+}
+
+/** 403: forbidden (private/deleted content, account restriction). */
+export class PixivForbiddenError extends PixivHttpError {
+  constructor(message: string, details: PixivErrorDetails & { body?: string } = {}) {
+    super(message, { status: 403, code: 'forbidden', retryable: false, ...details });
+    this.name = 'PixivForbiddenError';
+  }
+}
+
+/** 404: endpoint or work does not exist. Never retried. */
+export class PixivNotFoundError extends PixivHttpError {
+  constructor(message: string, details: PixivErrorDetails & { body?: string } = {}) {
+    super(message, { status: 404, code: 'not_found', retryable: false, ...details });
+    this.name = 'PixivNotFoundError';
+  }
+}
+
+/**
+ * 429 / rate limited. `retryAfterMs` carries the gate cooldown. The shared
+ * gate has ALREADY applied this cooldown by the time this is thrown, so the
+ * durable caller (scheduler/outbox) should back off rather than retry tight.
+ */
+export class PixivRateLimitError extends PixivHttpError {
+  constructor(message: string, details: PixivErrorDetails & { body?: string } = {}) {
+    super(message, {
+      status: 429,
+      code: 'rate_limited',
+      retryable: true,
+      ...details,
+    });
+    this.name = 'PixivRateLimitError';
+  }
+}
+
+/** 5xx server error. */
+export class PixivServerError extends PixivHttpError {
+  constructor(message: string, details: PixivErrorDetails & { body?: string } = {}) {
+    super(message, { retryable: true, code: `http_${details.status ?? 500}`, ...details });
+    this.name = 'PixivServerError';
+  }
+}
+
+/**
+ * Circuit breaker is OPEN: requests fail fast instead of queuing dozens of
+ * tasks against a rate-limiting Pixiv. Retryable after `retryAfterMs`.
+ */
+export class PixivCircuitOpenError extends PixivError {
+  constructor(message: string, details: PixivErrorDetails = {}) {
+    super(message, { code: 'circuit_open', retryable: true, ...details });
+    this.name = 'PixivCircuitOpenError';
+  }
+}
+
+/** Caller-supplied AbortSignal aborted the operation. */
+export class PixivAbortError extends PixivError {
+  constructor(message = 'Operation aborted', details: PixivErrorDetails = {}) {
+    super(message, { code: 'aborted', retryable: false, ...details });
+    this.name = 'PixivAbortError';
+  }
+}
+
+/** Generic API-level error (unexpected payload shape, empty body, ...). */
+export class PixivApiError extends PixivError {
+  constructor(message: string, details: PixivErrorDetails = {}) {
+    super(message, { code: 'api_error', ...details });
+    this.name = 'PixivApiError';
+  }
+}
+
+/** True when the error originated from this kit (used by host adapters). */
+export function isPixivError(error: unknown): error is PixivError {
+  return error instanceof PixivError;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * @redtidev/pixiv-client — independent Pixiv App-API client kit.
+ *
+ * Small, stable public surface. Consumers must import from the package root;
+ * transport/rate-limit internals are exported as named members for advanced
+ * embedding (custom state stores, health UIs, test doubles) but the
+ * service-level API (PixivClient) is what stays semver-stable.
+ */
+
+export { PixivClient, createPixivClient } from './client';
+export type { CreatePixivClientOptions } from './client';
+
+export { StaticTokenProvider, isRefreshable } from './auth/types';
+export type { AccessTokenProvider, RefreshableAccessTokenProvider } from './auth/types';
+
+export {
+  RateLimitGate,
+  MemoryRateLimitStateStore,
+  DEFAULT_RATE_LIMIT,
+  parseRetryAfter,
+} from './rate-limit/RateLimitGate';
+export { Transport } from './transport/transport';
+export type { TransportConfig } from './transport/transport';
+export { paginate, firstPage } from './pagination';
+
+export {
+  IllustrationsApi,
+  NovelsApi,
+  TagsApi,
+  MediaApi,
+  UsersApi,
+} from './app-api/exports';
+
+export type {
+  IllustSearchOptions,
+  NovelSearchOptions,
+  RankingOptions,
+  UserWorksOptions,
+  IllustRankingMode,
+  NovelRankingMode,
+  SearchSort,
+  SearchTarget,
+  OnePageResult,
+} from './app-api/options';
+
+export type {
+  PixivUser,
+  PixivTag,
+  PixivIllust,
+  PixivIllustPage,
+  PixivNovel,
+  PixivNovelTextResponse,
+  UgoiraFrame,
+  UgoiraMetadata,
+  Paginated,
+  PixivListResponse,
+} from './models';
+
+export type {
+  PixivClientOptions,
+  ProxyOptions,
+  RateLimitOptions,
+  RateLimitState,
+  RateLimitStateStore,
+  RateLimitStatus,
+  RequestOptions,
+  PaginationOptions,
+  KitEvent,
+  KitEventListener,
+  FetchLike,
+  ResponseLike,
+} from './types';
+export { silentLogger } from './logger';
+export type { KitLogger } from './logger';
+
+export {
+  PixivError,
+  PixivHttpError,
+  PixivNetworkError,
+  PixivTimeoutError,
+  PixivRateLimitError,
+  PixivAuthenticationError,
+  PixivForbiddenError,
+  PixivNotFoundError,
+  PixivServerError,
+  PixivCircuitOpenError,
+  PixivAbortError,
+  PixivApiError,
+  isPixivError,
+} from './errors/errors';
+export type { PixivErrorDetails } from './errors/errors';

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

@@ -0,0 +1,18 @@
+/**
+ * Minimal structured logger port. Default is silent; hosts inject their own
+ * logger when wiring the client. The kit never logs credentials: the
+ * transport emits request events with URLs/hosts only.
+ */
+export interface KitLogger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+export const silentLogger: KitLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};

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

@@ -0,0 +1,117 @@
+/**
+ * Pixiv domain models as returned by the public App API
+ * (https://app-api.pixiv.net). These are wire-shape interfaces (snake_case
+ * matches Pixiv), intentionally uncoupled from any host application types.
+ */
+
+export interface PixivUser {
+  id: string;
+  name: string;
+  account?: string;
+  profile_image_urls?: Record<string, string>;
+}
+
+export interface PixivTag {
+  name: string;
+  translated_name?: string;
+  add_by_uploaded_user?: boolean;
+}
+
+export interface PixivImageUrls {
+  square_medium: string;
+  medium: string;
+  large: string;
+  original?: string;
+}
+
+export interface PixivIllustPage {
+  image_urls: PixivImageUrls;
+  meta_single_page?: { original_image_url?: string };
+}
+
+export interface PixivSeries {
+  id: number;
+  title: string;
+}
+
+export interface PixivIllust {
+  id: number;
+  title: string;
+  type?: 'illust' | 'manga' | 'ugoira';
+  /** Detail responses use illust_type; search/list responses use type. */
+  illust_type?: 'illust' | 'manga' | 'ugoira';
+  page_count: number;
+  user: PixivUser;
+  image_urls: {
+    square_medium: string;
+    medium: string;
+    large: string;
+  };
+  meta_single_page?: { original_image_url?: string };
+  meta_pages?: PixivIllustPage[];
+  create_date: string;
+  caption?: string;
+  total_bookmarks?: number;
+  total_view?: number;
+  bookmark_count?: number;
+  view_count?: number;
+  width?: number;
+  height?: number;
+  sanity_level?: number;
+  x_restrict?: number;
+  illust_ai_type?: number;
+  series?: PixivSeries | null;
+  tags?: PixivTag[];
+}
+
+export type PixivIllustPageItem = PixivIllustPage;
+
+export interface PixivNovel {
+  id: number;
+  title: string;
+  user: PixivUser;
+  create_date: string;
+  caption?: string;
+  text_length?: number;
+  total_bookmarks?: number;
+  total_view?: number;
+  bookmark_count?: number;
+  view_count?: number;
+  x_restrict?: number;
+  series?: PixivSeries | null;
+  tags?: PixivTag[];
+  image_urls?: Record<string, string>;
+}
+
+export interface PixivNovelTextResponse {
+  novel_text: string;
+  /**
+   * Marker/next-url style fields are endpoint-specific; the webview fallback
+   * parses only the text. Hosts should not rely on other fields.
+   */
+  [key: string]: unknown;
+}
+
+export interface UgoiraFrame {
+  file: string;
+  delay: number;
+}
+
+export interface UgoiraMetadata {
+  zip_urls: { medium?: string; original?: string };
+  frames: UgoiraFrame[];
+  silence_before?: number;
+  silence_after?: number;
+}
+
+/** Common envelope for Pixiv paginated list responses. */
+export interface PixivListResponse<T> {
+  next_url: string | null;
+  [key: string]: unknown;
+}
+
+export interface Paginated<T> {
+  items: T[];
+  /** Opaque next-page token (currently a full Pixiv next_url). */
+  nextCursor: string | null;
+}

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

@@ -0,0 +1,46 @@
+import type { PaginationOptions } from './types';
+import type { Paginated } from './models';
+
+/**
+ * Walk a Pixiv `next_url` page chain one page at a time. This never performs
+ * unbounded auto-pagination: callers pass `limit`/`maxPages` and can abort.
+ * The transport's global gate spaces the requests; there is no extra delay
+ * parameter here.
+ */
+export async function paginate<T>(
+  fetchPage: (cursor: string | null, signal?: AbortSignal) => Promise<{ items: T[]; next: string | null }>,
+  options: PaginationOptions = {}
+): Promise<Paginated<T>> {
+  const items: T[] = [];
+  const limit = options.limit;
+  const maxPages = options.maxPages ?? (limit ? Math.ceil(limit / 30) + 5 : 10);
+  let cursor = options.cursor ?? null;
+
+  for (let page = 0; page < maxPages; page++) {
+    if (options.signal?.aborted) break;
+    const result = await fetchPage(cursor, options.signal);
+    items.push(...result.items);
+    options.onPage?.(page, items.length);
+    cursor = result.next;
+    if (!cursor || !result.items.length) break;
+    if (limit !== undefined && items.length >= limit) break;
+  }
+
+  const sliced = limit !== undefined ? items.slice(0, limit) : items;
+  const more = items.length > sliced.length || (cursor !== null && sliced.length === items.length);
+  return { items: sliced, nextCursor: more ? cursor : null };
+}
+
+/**
+ * Fetch exactly ONE page (the first page when no cursor is given).
+ * Used by host applications that own their pagination loop (PixivFlow's
+ * date-aware search stops early).
+ */
+export async function firstPage<T>(
+  fetchPage: (cursor: string | null, signal?: AbortSignal) => Promise<{ items: T[]; next: string | null }>,
+  cursor?: string | null,
+  signal?: AbortSignal
+): Promise<Paginated<T>> {
+  const result = await fetchPage(cursor ?? null, signal);
+  return { items: result.items, nextCursor: result.next };
+}