@book000/pixivts 0.55.1 → 0.56.0

package/dist/index.d.cts

@@ -0,0 +1,1659 @@
+/**
+ * Zero-dependency Result / ResultAsync implementation.
+ *
+ * Ergonomics are intentionally close to neverthrow so the patterns feel
+ * familiar without pulling in an external dependency.
+ *
+ * @example
+ * ```ts
+ * const r = ok(42)
+ * if (r.isOk) console.log(r.value) // 42
+ *
+ * const a = ResultAsync.fromPromise(fetch('/api'), (e) => networkError(e))
+ * const text = await a
+ *   .andThen((res) => ResultAsync.fromPromise(res.text(), networkError))
+ *   .unwrapOr('fallback')
+ * ```
+ */
+/** Successful result carrying `value`. */
+interface OkResult<T> {
+    /** Always `true` — use this to narrow the union to `OkResult<T>`. */
+    readonly isOk: true;
+    /** Always `false` — use this to narrow the union to `OkResult<T>`. */
+    readonly isErr: false;
+    /** The success value. */
+    readonly value: T;
+    /** Returns an `OkResult` with `fn(value)`. */
+    map<U>(fn: (value: T) => U): OkResult<U>;
+    /** Returns `this` unchanged. */
+    mapErr<F>(_fn: (error: never) => F): OkResult<T>;
+    /** Calls `fn(value)` and returns its Result. */
+    andThen<U, F>(fn: (value: T) => Result<U, F>): Result<U, F>;
+    /** Calls `onOk` and returns its result. */
+    match<U>(onOk: (value: T) => U, _onErr: (error: never) => U): U;
+    /** Returns `value`. */
+    unwrapOr(_fallback: T): T;
+}
+/** Failed result carrying `error`. */
+interface ErrResult<E> {
+    /** Always `false` — use this to narrow the union to `ErrResult<E>`. */
+    readonly isOk: false;
+    /** Always `true` — use this to narrow the union to `ErrResult<E>`. */
+    readonly isErr: true;
+    /** The error value. */
+    readonly error: E;
+    /** Returns `this` unchanged. */
+    map<U>(_fn: (value: never) => U): ErrResult<E>;
+    /** Returns an `ErrResult` with `fn(error)`. */
+    mapErr<F>(fn: (error: E) => F): ErrResult<F>;
+    /** Returns `this` unchanged. */
+    andThen<U, F>(_fn: (value: never) => Result<U, F>): ErrResult<E>;
+    /** Calls `onErr` and returns its result. */
+    match<U>(_onOk: (value: never) => U, onErr: (error: E) => U): U;
+    /** Returns `fallback`. */
+    unwrapOr<T>(fallback: T): T;
+}
+/** A value that is either `OkResult<T>` or `ErrResult<E>`. */
+type Result<T, E> = OkResult<T> | ErrResult<E>;
+/**
+ * Creates a successful `Result<T, never>`.
+ *
+ * @param value - The success value
+ */
+declare function ok<T>(value: T): OkResult<T>;
+/**
+ * Creates a failed `Result<never, E>`.
+ *
+ * @param error - The error value
+ */
+declare function err<E>(error: E): ErrResult<E>;
+/**
+ * A `PromiseLike<Result<T, E>>` that is directly `await`-able and supports
+ * chainable `map / mapErr / andThen` operators.
+ *
+ * @example
+ * ```ts
+ * const result = await ResultAsync.fromPromise(fetch('/api'), networkError)
+ *   .andThen((res) =>
+ *     ResultAsync.fromPromise(res.json() as Promise<unknown>, networkError)
+ *   )
+ * ```
+ */
+declare class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
+    private readonly _promise;
+    constructor(promise: Promise<Result<T, E>>);
+    then<TResult1 = Result<T, E>, TResult2 = never>(onfulfilled?: ((value: Result<T, E>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Wraps a `Promise<T>` into a `ResultAsync<T, E>`.
+     *
+     * If the promise rejects, `onError` maps the rejection reason to `E`.
+     *
+     * @param promise - The promise to wrap
+     * @param onError - Error mapper
+     */
+    static fromPromise<T, E>(promise: Promise<T>, onError: (reason: unknown) => E): ResultAsync<T, E>;
+    /**
+     * Wraps an already-resolved `Result<T, E>` into a `ResultAsync<T, E>`.
+     *
+     * @param result - The result to wrap
+     */
+    static fromResult<T, E>(result: Result<T, E>): ResultAsync<T, E>;
+    /**
+     * Transforms the success value.
+     *
+     * If the inner result is `Err`, `fn` is not called.
+     *
+     * @param fn - Synchronous mapper
+     */
+    map<U>(fn: (value: T) => U): ResultAsync<U, E>;
+    /**
+     * Transforms the error value.
+     *
+     * If the inner result is `Ok`, `fn` is not called.
+     *
+     * @param fn - Synchronous error mapper
+     */
+    mapErr<F>(fn: (error: E) => F): ResultAsync<T, F>;
+    /**
+     * Chains another async operation that may fail.
+     *
+     * If the inner result is `Err`, `fn` is not called.
+     *
+     * @param fn - Async mapper that returns a `ResultAsync<U, F>`
+     */
+    andThen<U, F>(fn: (value: T) => ResultAsync<U, F> | Result<U, F>): ResultAsync<U, E | F>;
+    /**
+     * Pattern-matches on success / failure.
+     *
+     * @param onOk - Called with the success value
+     * @param onErr - Called with the error value
+     * @returns A `Promise<U>`
+     */
+    match<U>(onOk: (value: T) => U | Promise<U>, onErr: (error: E) => U | Promise<U>): Promise<U>;
+    /**
+     * Returns the success value, or `fallback` if the result is `Err`.
+     *
+     * @param fallback - The fallback value
+     */
+    unwrapOr(fallback: T): Promise<T>;
+}
+
+/**
+ * Authentication manager for the pixiv API.
+ *
+ * Handles the OAuth 2.0 token refresh flow and generates the
+ * x-client-hash header required by the pixiv iOS app API.
+ *
+ * The MD5 implementation is pure TypeScript to ensure Edge/browser compatibility —
+ * Node's `crypto.createHash('md5')` is unavailable in Edge runtimes, and
+ * `crypto.subtle` does not support MD5 (non-cryptographic hash).
+ */
+/** Auth credentials returned by the pixiv token endpoint. */
+interface AuthCredentials {
+    /** Numeric user ID returned as a string by the token endpoint. */
+    userId: string;
+    /** Short-lived bearer token for API requests. */
+    accessToken: string;
+    /** Long-lived token used to obtain new access tokens. */
+    refreshToken: string;
+}
+/**
+ * Manages access tokens for the pixiv API.
+ *
+ * Holds the current access token and refresh token in memory.
+ * The refresh() method exchanges the refresh token for a new access token
+ * via the pixiv OAuth endpoint.
+ */
+declare class AuthManager {
+    #private;
+    userId: string;
+    constructor(credentials: AuthCredentials);
+    /** Returns the current access token. */
+    get accessToken(): string;
+    /** Returns the current refresh token. */
+    get refreshToken(): string;
+    /**
+     * Exchanges the stored refresh token for a fresh access token.
+     *
+     * Updates the internal credentials on success.
+     * Throws if the token endpoint returns a non-200 response.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Creates an `AuthManager` by performing the initial token refresh.
+     *
+     * @param refreshToken - Pixiv refresh token
+     * @returns Initialized `AuthManager`
+     */
+    static login(refreshToken: string): Promise<AuthManager>;
+}
+
+/**
+ * Response interceptor types for the pixiv API client.
+ *
+ * The interceptor is the seam that connects `@book000/pixivts-db-mysql`
+ * (or any other storage backend) to the HTTP layer without introducing a
+ * runtime dependency in core.
+ *
+ * Usage:
+ * ```ts
+ * import { createResponseRecorder } from '@book000/pixivts-db-mysql'
+ * const { interceptor, close } = await createResponseRecorder({ ... })
+ * const client = await PixivClient.of(token, { onResponse: interceptor })
+ * ```
+ */
+/** HTTP method of the request. */
+type HttpMethod = 'GET' | 'POST';
+/**
+ * A single API response record passed to the interceptor after every successful
+ * HTTP call made by the pixiv client.
+ */
+interface ResponseRecord {
+    /** HTTP method used for the request. */
+    method: HttpMethod;
+    /** API endpoint path (e.g. "/v1/illust/detail"). */
+    endpoint: string;
+    /** Full request URL including query string (null if unavailable). */
+    url: string | null;
+    /** JSON-serialized request headers (null if unavailable). */
+    requestHeaders: string | null;
+    /** URL-encoded request body for POST requests (null for GET). */
+    requestBody: string | null;
+    /** Whether the response body was parsed as JSON or left as plain text. */
+    responseType: 'JSON' | 'TEXT';
+    /** HTTP response status code. */
+    statusCode: number;
+    /** JSON-serialized response headers (null if unavailable). */
+    responseHeaders: string | null;
+    /** Serialized response body. */
+    responseBody: string;
+}
+/**
+ * A callback invoked after every successful API response.
+ *
+ * Implementations should be non-blocking — awaiting a slow DB write here will
+ * add latency to every API call.  Consider queueing the record and writing
+ * asynchronously if persistence latency matters.
+ */
+type ResponseInterceptor = (record: ResponseRecord) => void | Promise<void>;
+
+/**
+ * Discriminated union of all errors that can occur when using the pixiv API client.
+ *
+ * Use the `type` field to discriminate:
+ * ```ts
+ * if (result.isErr) {
+ *   const err = result.error
+ *   if (err.type === 'rate_limit') { ... }
+ * }
+ * ```
+ */
+type PixivError = {
+    /** The request hit the rate limit and exhausted all retries. */
+    type: 'rate_limit';
+    /** Retry-After duration parsed from the last 429 response (milliseconds). */
+    retryAfter: number;
+} | {
+    /** Authentication failed (401 response that could not be refreshed). */
+    type: 'auth_failed';
+    /** HTTP status code (always 401). */
+    status: number;
+} | {
+    /** A network-level error occurred (fetch threw). */
+    type: 'network';
+    /** The underlying error thrown by fetch. */
+    cause: unknown;
+} | {
+    /** The API returned a non-2xx status code other than 401/429. */
+    type: 'api_error';
+    /** HTTP status code. */
+    status: number;
+    /** Parsed response body (object if JSON, string otherwise). */
+    body: unknown;
+};
+/**
+ * An `Error` subclass that wraps a `PixivError` for use in thrown contexts
+ * (e.g. async generators that must throw proper `Error` objects).
+ *
+ * All `PixivError` properties are spread directly onto this instance so that
+ * callers can use `instanceof PixivFetchError` or access `error.type` etc.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   for await (const page of result.pages()) { ... }
+ * } catch (e) {
+ *   if (e instanceof PixivFetchError) {
+ *     console.error(e.pixivError.type)
+ *   }
+ * }
+ * ```
+ */
+declare class PixivFetchError extends Error {
+    /** The underlying structured `PixivError`. */
+    readonly pixivError: PixivError;
+    constructor(pixivError: PixivError);
+}
+/** Creates a rate-limit error. */
+declare function rateLimitError(retryAfter: number): PixivError;
+/** Creates an auth-failed error. */
+declare function authFailedError(status: number): PixivError;
+/** Creates a network error. */
+declare function networkError(cause: unknown): PixivError;
+/** Creates an API error. */
+declare function apiError(status: number, body: unknown): PixivError;
+
+/**
+ * HTTP client for the pixiv API.
+ *
+ * Wraps the global `fetch` API and adds:
+ *   - 429 retry with Retry-After header parsing
+ *   - 401 → token refresh → single retry
+ *   - Response interceptor hook (for optional DB recording)
+ *   - Image fetch helper (browser UA, Referer, no auth)
+ */
+
+/** Options for controlling retry behaviour on rate-limited requests. */
+interface RateLimitRetryOptions {
+    /** Maximum number of retries when a 429 response is received. Defaults to 3. */
+    maxRetries: number;
+    /** Default wait time (ms) used when no Retry-After header is present. Defaults to 10_000. */
+    waitMs: number;
+}
+/**
+ * HTTP client for the pixiv API.
+ *
+ * All methods return `ResultAsync<T, PixivError>` — no throws.
+ * A 429 → retry loop and a 401 → refresh → retry are handled internally.
+ */
+declare class HttpClient {
+    #private;
+    constructor(auth: AuthManager, options?: {
+        retry?: Partial<RateLimitRetryOptions>;
+        onResponse?: ResponseInterceptor;
+    });
+    /**
+     * Sends a GET request to the pixiv API.
+     *
+     * @param path - API endpoint path (e.g. "/v1/illust/detail")
+     * @param params - Query parameters as a URLSearchParams instance
+     * @returns `ResultAsync<T, PixivError>`
+     */
+    get<T>(path: string, params?: URLSearchParams): ResultAsync<T, PixivError>;
+    /**
+     * Sends a POST request to the pixiv API.
+     *
+     * @param path - API endpoint path (e.g. "/v2/illust/bookmark/add")
+     * @param body - URL-encoded request body string
+     * @returns `ResultAsync<T, PixivError>`
+     */
+    post<T>(path: string, body: string): ResultAsync<T, PixivError>;
+    /**
+     * Fetches a pixiv image URL without an Authorization header.
+     *
+     * Uses a browser User-Agent and the pixiv Referer, which are required for
+     * image CDN access. Retry and interceptor are not applied here.
+     *
+     * @param imageUrl - Full image URL
+     * @returns `ResultAsync<Response, PixivError>`
+     */
+    fetchImage(imageUrl: string): ResultAsync<Response, PixivError>;
+    /**
+     * Sends a request to an absolute URL returned in a `next_url` field.
+     *
+     * Applies the same retry / interceptor / auth logic as `get()`.
+     *
+     * @param absoluteUrl - Full URL including query string
+     * @returns `ResultAsync<T, PixivError>`
+     */
+    getAbsolute<T>(absoluteUrl: string): ResultAsync<T, PixivError>;
+}
+
+/**
+ * PaginatedResultAsync — pagination support for the pixiv API.
+ *
+ * Extends `ResultAsync<TPage, PixivError>` so that:
+ *   - `await paginated` returns the first-page `Result<TPage, PixivError>` directly
+ *   - `.pages()` is an async generator that yields each page
+ *   - `.items()` is an async generator that yields individual items across all pages
+ *
+ * Pagination uses the `next_url` field returned by list endpoints. The URL is
+ * fetched via `HttpClient.getAbsolute()` which reuses the same auth / retry /
+ * interceptor pipeline as regular requests.
+ */
+
+/**
+ * A page returned by a pixiv list endpoint.
+ *
+ * Must have a `next_url` field (null when there are no more pages).
+ */
+interface PagedResponse {
+    /** URL to the next page, or `null` when there are no more pages. */
+    next_url: string | null;
+}
+/**
+ * A `ResultAsync<TPage, PixivError>` with additional `.pages()` / `.items()`
+ * async generators for consuming paginated pixiv list responses.
+ *
+ * Returned by all resource methods that produce a `next_url` field.
+ */
+declare class PaginatedResultAsync<TPage extends PagedResponse, TItem> extends ResultAsync<TPage, PixivError> {
+    #private;
+    constructor(promise: Promise<Result<TPage, PixivError>>, http: HttpClient, getItems: (page: TPage) => TItem[]);
+    /**
+     * Creates a `PaginatedResultAsync` from a `ResultAsync`.
+     *
+     * @param inner - The first-page result
+     * @param http - HTTP client for fetching subsequent pages
+     * @param getItems - Extracts item array from a page
+     */
+    static fromResultAsync<TPage extends PagedResponse, TItem>(inner: ResultAsync<TPage, PixivError>, http: HttpClient, getItems: (page: TPage) => TItem[]): PaginatedResultAsync<TPage, TItem>;
+    /**
+     * Async generator that yields each page starting from the first.
+     *
+     * If any page fetch fails, the generator throws a `PixivFetchError`.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.illusts.search({ word: 'cat' }).pages()) {
+     *   console.log(page.illusts.length)
+     * }
+     * ```
+     */
+    pages(): AsyncGenerator<TPage, void, unknown>;
+    /**
+     * Async generator that yields individual items across all pages.
+     *
+     * If any page fetch fails, the generator throws a `PixivFetchError`.
+     *
+     * @example
+     * ```ts
+     * for await (const illust of client.illusts.search({ word: 'cat' }).items()) {
+     *   console.log(illust.title)
+     * }
+     * ```
+     */
+    items(): AsyncGenerator<TItem, void, unknown>;
+}
+/**
+ * Creates an immediately-failed `PaginatedResultAsync`.
+ *
+ * Useful when validation or auth fails before any HTTP request is made.
+ *
+ * @param error - The error to return
+ * @param http - HTTP client (used for signature compatibility)
+ * @param getItems - Item extractor (used for signature compatibility)
+ */
+declare function failedPaginated<TPage extends PagedResponse, TItem>(error: PixivError, http: HttpClient, getItems: (page: TPage) => TItem[]): PaginatedResultAsync<TPage, TItem>;
+
+/**
+ * Public option types for @book000/pixivts.
+ *
+ * All types are string literal unions — NOT TypeScript enums — so callers
+ * do not need to import a runtime value and the values are transparent in
+ * serialised output.
+ */
+/**
+ * Search match target for illust / novel searches.
+ *
+ * - `partial_match_for_tags` — tags contain the word (default)
+ * - `exact_match_for_tags` — tags exactly equal the word
+ * - `title_and_caption` — title or caption contains the word
+ * - `keyword` — general keyword search (novel only)
+ */
+type SearchTarget = 'partial_match_for_tags' | 'exact_match_for_tags' | 'title_and_caption' | 'keyword';
+/**
+ * Sort order for search results.
+ *
+ * - `date_desc` — newest first (default)
+ * - `date_asc` — oldest first
+ * - `popular_desc` — most bookmarks first (premium only)
+ */
+type SearchSort = 'date_desc' | 'date_asc' | 'popular_desc';
+/**
+ * Date range filter for search results.
+ *
+ * - `within_last_day` — past 24 hours
+ * - `within_last_week` — past 7 days
+ * - `within_last_month` — past 30 days
+ */
+type SearchDuration = 'within_last_day' | 'within_last_week' | 'within_last_month';
+/**
+ * Ranking mode for illust rankings.
+ *
+ * R-18 modes require a premium account with R-18 content enabled.
+ */
+type RankingMode = 'day' | 'day_male' | 'day_female' | 'week_original' | 'week_rookie' | 'week' | 'month' | 'day_ai' | 'day_r18' | 'week_r18' | 'day_male_r18' | 'day_female_r18' | 'day_r18_ai';
+/**
+ * Ranking mode for novel rankings.
+ *
+ * R-18 modes require a premium account with R-18 content enabled.
+ */
+type NovelRankingMode = 'day' | 'week' | 'day_male' | 'day_female' | 'week_rookie' | 'day_r18' | 'week_r18' | 'day_r18_ai';
+/**
+ * Visibility restriction for bookmarks.
+ *
+ * - `public` — publicly visible (default)
+ * - `private` — visible only to the owner
+ */
+type BookmarkRestrict = 'public' | 'private';
+/**
+ * Visibility restriction for follows.
+ *
+ * - `public` — publicly visible (default)
+ * - `private` — visible only to the owner
+ */
+type FollowRestrict = 'public' | 'private';
+/**
+ * OS filter used to request works compatible with the given platform.
+ *
+ * - `for_ios` — iOS-compatible works (default)
+ * - `for_android` — Android-compatible works
+ */
+type OSFilter = 'for_ios' | 'for_android';
+/**
+ * Work type filter for user illust listings.
+ *
+ * - `illust` — illustrations only
+ * - `manga` — manga only
+ */
+type UserIllustType = 'illust' | 'manga';
+
+/**
+ * Public types for @book000/pixivts.
+ *
+ * These are explicitly-written TypeScript interfaces — NOT derived via
+ * `z.infer<>` at this level — to guarantee that the built `.d.ts` files
+ * contain no zod references.  The corresponding zod schemas in `src/schemas/`
+ * exist solely for internal use (tests, safeParse fixture validation).
+ *
+ * Correctness is verified by `expectTypeOf` checks in `tests/types.test.ts`.
+ */
+/**
+ * Image URLs for a work (thumbnail variants).
+ *
+ * Accessing these URLs requires setting an appropriate `Referer` header.
+ */
+interface ImageUrls {
+    /** 360×360 thumbnail */
+    square_medium: string;
+    /** Long side ≤ 540 px */
+    medium: string;
+    /** Width ≤ 600 px, height ≤ 1200 px */
+    large: string;
+    /** Original image (present in `meta_pages` entries only) */
+    original?: string;
+}
+/** Profile image URLs for a user. */
+interface ProfileImageUrls {
+    /** Medium-size profile image URL. */
+    medium: string;
+}
+/**
+ * Minimal user info embedded in works, search results, and preview lists.
+ *
+ * Full profile data is returned by GET /v1/user/detail.
+ */
+interface PixivUser {
+    /**
+     * Internal numeric user ID.
+     *
+     * NOTE: certain API endpoints return this as a string.  The core library
+     * normalises it to `number` before returning it to callers.
+     */
+    id: number;
+    /** Display name shown on the user's profile. */
+    name: string;
+    /** Login account name (distinct from the display `name`). */
+    account: string;
+    /** Set of profile image URLs at different sizes. */
+    profile_image_urls: ProfileImageUrls;
+    /** Whether the authenticated user follows this user. */
+    is_followed?: boolean;
+    /** Whether this user has blocked access by the authenticated user. */
+    is_access_blocking_user?: boolean;
+    /** Whether this user accepts illustration commission requests. */
+    is_accept_request?: boolean;
+}
+/** Tag on a work. */
+interface Tag {
+    /** Tag name in Japanese. */
+    name: string;
+    /** Translated tag name, or `null` if no translation is available. */
+    translated_name: string | null;
+    /** Whether the tag was added by the work's uploader. */
+    added_by_uploaded_user?: boolean;
+}
+/** Series information embedded in a work item. */
+interface Series {
+    /** Series ID. */
+    id: number;
+    /** Series title. */
+    title: string;
+}
+/** Privacy-policy blurb returned by recommended endpoints. */
+interface PrivacyPolicy {
+    /** Policy version string. */
+    version?: string;
+    /** Human-readable policy notice. */
+    message?: string;
+    /** URL to the full privacy-policy page. */
+    url?: string;
+}
+/** Original-image URL for a single-page illust. */
+interface MetaSinglePage {
+    /** Direct URL to the original-resolution image. */
+    original_image_url: string;
+}
+/** Per-page image URLs for a multi-page work (manga). */
+interface MetaPages {
+    /** Full set of image URLs for this page, including the original. */
+    image_urls: Required<ImageUrls>;
+}
+/**
+ * A pixiv illust or manga work item as returned by the API.
+ *
+ * Returned by GET /v1/illust/detail, GET /v1/search/illust,
+ * GET /v1/illust/ranking, GET /v1/illust/recommended, etc.
+ */
+interface PixivIllustItem {
+    /**
+     * Work ID.
+     *
+     * Illusts and novels are numbered in separate sequences — the same ID
+     * can appear in both.
+     */
+    id: number;
+    /** Title of the work. */
+    title: string;
+    /** Work category: illustration, manga, or animated illustration. */
+    type: 'illust' | 'manga' | 'ugoira';
+    /** Thumbnail image URLs at various sizes. */
+    image_urls: ImageUrls;
+    /** Work caption / description (may contain HTML). */
+    caption: string;
+    /** Content restriction level (0 = public, 1 = mypixiv-only, 2 = private). */
+    restrict: number;
+    /** Author of the work. */
+    user: PixivUser;
+    /** Tags attached to the work. */
+    tags: Tag[];
+    /** Creation tools listed by the author (e.g. "Photoshop"). */
+    tools: string[];
+    /** ISO 8601 date-time string of when the work was posted. */
+    create_date: string;
+    /** Number of images in a multi-page work (1 for single-page). */
+    page_count: number;
+    /** Canvas width in pixels. */
+    width: number;
+    /** Canvas height in pixels. */
+    height: number;
+    /** Sanity / sensitivity level assigned by the pixiv content filter. */
+    sanity_level: number;
+    /** Age restriction: 0 = all-ages, 1 = R-18, 2 = R-18G */
+    x_restrict: number;
+    /** Series this work belongs to, or `null` if not part of a series. */
+    series: Series | null;
+    /**
+     * For single-page works: `{ original_image_url: string }`.
+     * For multi-page works: `{}` (empty object).
+     */
+    meta_single_page: MetaSinglePage | Record<string, never>;
+    /** Per-page image URLs for multi-page works (empty array for single-page). */
+    meta_pages: MetaPages[];
+    /** Total number of views. */
+    total_view: number;
+    /** Total number of bookmarks. */
+    total_bookmarks: number;
+    /** Whether the authenticated user has bookmarked this work. */
+    is_bookmarked: boolean;
+    /** Whether the work is publicly visible. */
+    visible: boolean;
+    /** Whether the work is muted for the authenticated user. */
+    is_muted: boolean;
+    /** Total number of comments (may be absent on some endpoints). */
+    total_comments?: number;
+    /** AI-generated content flag: 0 = no AI, 1 = partial AI, 2 = fully AI */
+    illust_ai_type: number;
+    /** Book-style rendering flag (0 = normal, 1 = book). */
+    illust_book_style: number;
+    /** Controls who can post comments (may be absent). */
+    comment_access_control?: number;
+    /** Additional access-restriction attributes (may be absent). */
+    restriction_attributes?: string[];
+}
+/** Illust series metadata returned by GET /v1/illust/series. */
+interface IllustSeriesDetail {
+    /** Series ID. */
+    id: number;
+    /** Series title. */
+    title: string;
+    /** Series description / caption. */
+    caption: string;
+    /** Cover image URLs. */
+    cover_image_urls: {
+        medium: string;
+    };
+    /** Number of works in the series. */
+    series_work_count: number;
+    /** ISO 8601 date-time string of when the series was created. */
+    create_date: string;
+    /** Canvas width of the cover image in pixels. */
+    width: number;
+    /** Canvas height of the cover image in pixels. */
+    height: number;
+    /** Author of the series. */
+    user: PixivUser;
+    /** Whether the authenticated user has added this series to their watchlist. */
+    watchlist_added: boolean;
+}
+/**
+ * A pixiv novel work item as returned by the API.
+ *
+ * Returned by GET /v2/novel/detail, GET /v1/search/novel, etc.
+ */
+interface PixivNovelItem {
+    /**
+     * Work ID.
+     *
+     * Novels and illusts are numbered in separate sequences — the same ID
+     * can appear in both.
+     */
+    id: number;
+    /** Title of the novel. */
+    title: string;
+    /** Synopsis / caption (may contain HTML). */
+    caption: string;
+    /** Content restriction level (0 = public, 1 = mypixiv-only, 2 = private). */
+    restrict: number;
+    /** Age restriction: 0 = all-ages, 1 = R-18, 2 = R-18G */
+    x_restrict: number;
+    /** Whether the novel is an original work (not fan fiction). */
+    is_original: boolean;
+    /** Cover image URLs. */
+    image_urls: ImageUrls;
+    /** ISO 8601 date-time string of when the novel was posted. */
+    create_date: string;
+    /** Tags attached to the novel. */
+    tags: Tag[];
+    /** Number of pages (word-count chunks). */
+    page_count: number;
+    /** Total character count of the novel body. */
+    text_length: number;
+    /** Author of the novel. */
+    user: PixivUser;
+    /**
+     * Series information.
+     *
+     * `{}` (empty object) if the novel does not belong to a series.
+     */
+    series: Series | Record<string, never>;
+    /** Whether the authenticated user has bookmarked this novel. */
+    is_bookmarked: boolean;
+    /** Total number of bookmarks. */
+    total_bookmarks: number;
+    /** Total number of views. */
+    total_view: number;
+    /** Whether the novel is publicly visible. */
+    visible: boolean;
+    /** Total number of comments. */
+    total_comments: number;
+    /** Whether the novel is muted for the authenticated user. */
+    is_muted: boolean;
+    /** Whether the novel is restricted to mutual followers (mypixiv). */
+    is_mypixiv_only: boolean;
+    /** Whether the novel contains explicit content beyond the `x_restrict` flag. */
+    is_x_restricted: boolean;
+    /** AI-generated content flag: 0 = no AI, 1 = partial AI, 2 = fully AI */
+    novel_ai_type: number;
+    /** Controls who can post comments (may be absent). */
+    comment_access_control?: number;
+}
+/** Novel series details returned by GET /v2/novel/series. */
+interface NovelSeriesDetail {
+    /** Series ID. */
+    id: number;
+    /** Series title. */
+    title: string;
+    /** Series description / caption. */
+    caption: string;
+    /** Whether every novel in the series is original (not fan fiction). */
+    is_original: boolean;
+    /** Whether the series has been marked as concluded by the author. */
+    is_concluded: boolean;
+    /** Number of novels in the series. */
+    content_count: number;
+    /** Total character count across all novels in the series. */
+    total_character_count: number;
+    /** Author of the series. */
+    user: PixivUser;
+    /** Human-readable series label / tagline. */
+    display_text: string;
+    /** AI-generated content flag: 0 = no AI, 1 = partial AI, 2 = fully AI */
+    novel_ai_type: number;
+    /** Whether the authenticated user has added this series to their watchlist. */
+    watchlist_added: boolean;
+}
+/** User item with self-introduction; embedded in GET /v1/user/detail. */
+type PixivUserItem = PixivUser & {
+    /** Self-introduction text (line endings are \r\n) */
+    comment: string;
+};
+/** Visibility setting for a user profile field. */
+type Publicity = 'public' | 'private' | 'mypixiv';
+/** Detailed profile information for a user. */
+interface PixivUserProfile {
+    /** Personal website URL, or `null` if not set. */
+    webpage: string | null;
+    /** Disclosed gender. */
+    gender: 'male' | 'female' | 'unknown';
+    /** Birth date string (YYYY-MM-DD format, may be partial). */
+    birth: string;
+    /** Birth day portion (MM-DD format). */
+    birth_day: string;
+    /** Birth year. */
+    birth_year: number;
+    /** Region / prefecture. */
+    region: string;
+    /** Internal address ID. */
+    address_id: number;
+    /** Two-letter country code (ISO 3166-1 alpha-2). */
+    country_code: string;
+    /** Occupation / job description. */
+    job: string;
+    /** Internal job category ID. */
+    job_id: number;
+    /** Number of users this user follows. */
+    total_follow_users: number;
+    /** Number of mutual-follow (mypixiv) connections. */
+    total_mypixiv_users: number;
+    /** Total number of public illusts. */
+    total_illusts: number;
+    /** Total number of public manga works. */
+    total_manga: number;
+    /** Total number of public novels. */
+    total_novels: number;
+    /** Total number of publicly bookmarked illusts. */
+    total_illust_bookmarks_public: number;
+    /** Total number of illust series. */
+    total_illust_series: number;
+    /** Total number of novel series. */
+    total_novel_series: number;
+    /** Profile background image URL, or `null` if not set. */
+    background_image_url: string | null;
+    /** Linked Twitter/X account name (without @). */
+    twitter_account: string;
+    /** Twitter/X profile URL, or `null` if not set. */
+    twitter_url: string | null;
+    /** Pawoo profile URL, or `null` if not set. */
+    pawoo_url: string | null;
+    /** Whether the user has a premium (paid) account. */
+    is_premium: boolean;
+    /** Whether the user has set a custom profile image. */
+    is_using_custom_profile_image: boolean;
+}
+/** Visibility settings for a user's profile fields. */
+interface PixivUserProfilePublicity {
+    /** Visibility of the gender field. */
+    gender: Publicity;
+    /** Visibility of the region field. */
+    region: Publicity;
+    /** Visibility of the birth-day field. */
+    birth_day: Publicity;
+    /** Visibility of the birth-year field. */
+    birth_year: Publicity;
+    /** Visibility of the job field. */
+    job: Publicity;
+    /** Whether the Pawoo account link is visible. */
+    pawoo: boolean;
+}
+/** Workspace / desk setup information from a user's profile. */
+interface PixivUserProfileWorkspace {
+    /** PC / computer specs. */
+    pc: string;
+    /** Monitor model. */
+    monitor: string;
+    /** Drawing software / tool. */
+    tool: string;
+    /** Scanner model. */
+    scanner: string;
+    /** Tablet model. */
+    tablet: string;
+    /** Mouse model. */
+    mouse: string;
+    /** Printer model. */
+    printer: string;
+    /** Desktop wallpaper or environment description. */
+    desktop: string;
+    /** Music / background audio description. */
+    music: string;
+    /** Desk description. */
+    desk: string;
+    /** Chair description. */
+    chair: string;
+    /** Free-text comment about the workspace. */
+    comment: string;
+    /** Workspace image URL, or `null` if not set. */
+    workspace_image_url: string | null;
+}
+/**
+ * Preview item for a user in the GET /v1/user/following response.
+ *
+ * Contains a few sample illusts and novels from that user.
+ */
+interface PixivUserPreviewItem {
+    /** The user being previewed. */
+    user: PixivUser;
+    /** A small sample of the user's recent illusts. */
+    illusts: PixivIllustItem[];
+    /** A small sample of the user's recent novels. */
+    novels: PixivNovelItem[];
+    /** Whether this user is muted by the authenticated user. */
+    is_muted: boolean;
+}
+/** URLs for ugoira frame archives (ZIP files). */
+interface ZipUrls {
+    /** URL for the 600 px-long-side archive. */
+    medium: string;
+}
+/** Timing info for a single ugoira frame. */
+interface Frame {
+    /** File name within the ZIP archive */
+    file: string;
+    /** Display duration in milliseconds */
+    delay: number;
+}
+/** Ugoira metadata as returned by GET /v1/ugoira/metadata. */
+interface PixivUgoiraItem {
+    /** Archive URLs for the frame ZIP. */
+    zip_urls: ZipUrls;
+    /** Per-frame timing data (in order). */
+    frames: Frame[];
+}
+/**
+ * Shape of the JSON body returned by the pixiv API on error.
+ */
+interface PixivApiErrorBody {
+    /** Error payload returned by the pixiv API. */
+    error: {
+        /** Localised error message intended for end users. */
+        user_message: string;
+        /** Internal error message. */
+        message: string;
+        /** Short error reason / code. */
+        reason: string;
+        /** Additional details for the user-facing message (may be absent). */
+        user_message_details?: Record<string, unknown>;
+    };
+}
+/** Response shape for GET /v1/illust/detail. */
+interface IllustDetailResponse {
+    /** The requested illust. */
+    illust: PixivIllustItem;
+}
+/** Page response for illust list endpoints (search, related, ranking, etc.). */
+interface IllustListPage {
+    /** Illusts on this page. */
+    illusts: PixivIllustItem[];
+    /**
+     * Whether AI-generated works are shown in the results.
+     *
+     * Only present on search responses; absent on related/ranking/recommended endpoints.
+     */
+    show_ai?: boolean;
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/illust/recommended. */
+interface IllustRecommendedPage {
+    /** Recommended illusts. */
+    illusts: PixivIllustItem[];
+    /** Ranking illusts included alongside recommendations. */
+    ranking_illusts: PixivIllustItem[];
+    /** Whether an ongoing contest exists. */
+    contest_exists: boolean;
+    /** Privacy-policy notice (present on the first page). */
+    privacy_policy?: PrivacyPolicy;
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/illust/series. */
+interface IllustSeriesPage {
+    /** Metadata for the series. */
+    illust_series_detail: IllustSeriesDetail;
+    /** First illust in the series. */
+    illust_series_first_illust: PixivIllustItem;
+    /** Illusts on this page. */
+    illusts: PixivIllustItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/manga/recommended. */
+interface MangaRecommendedPage {
+    /** Recommended manga works. */
+    illusts: PixivIllustItem[];
+    /** Ranking manga works included alongside recommendations. */
+    ranking_illusts: PixivIllustItem[];
+    /** Privacy-policy notice (present on the first page). */
+    privacy_policy?: PrivacyPolicy;
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Response shape for GET /v1/ugoira/metadata. */
+interface UgoiraMetadataResponse {
+    /** Ugoira metadata (ZIP URLs and per-frame timings). */
+    ugoira_metadata: PixivUgoiraItem;
+}
+/** Response shape for GET /v2/novel/detail. */
+interface NovelDetailResponse {
+    /** The requested novel. */
+    novel: PixivNovelItem;
+}
+/** Page response for novel list endpoints (search, related, ranking, etc.). */
+interface NovelListPage {
+    /** Novels on this page. */
+    novels: PixivNovelItem[];
+    /**
+     * Whether AI-generated works are shown in the results.
+     *
+     * Only present on search responses; absent on related/ranking/recommended endpoints.
+     */
+    show_ai?: boolean;
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/novel/recommended. */
+interface NovelRecommendedPage {
+    /** Recommended novels. */
+    novels: PixivNovelItem[];
+    /** Ranking novels included alongside recommendations. */
+    ranking_novels: PixivNovelItem[];
+    /** Privacy-policy notice (present on the first page). */
+    privacy_policy?: PrivacyPolicy;
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v2/novel/series. */
+interface NovelSeriesPage {
+    /** Metadata for the series. */
+    novel_series_detail: NovelSeriesDetail;
+    /** First novel in the series. */
+    novel_series_first_novel: PixivNovelItem;
+    /** Most recently published novel in the series. */
+    novel_series_latest_novel: PixivNovelItem;
+    /** Novels on this page. */
+    novels: PixivNovelItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Response shape for GET /v1/user/detail. */
+interface UserDetailResponse {
+    /** Basic user info with self-introduction. */
+    user: PixivUserItem;
+    /** Detailed profile data. */
+    profile: PixivUserProfile;
+    /** Visibility settings for profile fields. */
+    profile_publicity: PixivUserProfilePublicity;
+    /** Workspace / desk-setup information. */
+    workspace: PixivUserProfileWorkspace;
+}
+/** Page response for GET /v1/user/illusts. */
+interface UserIllustsPage {
+    /** The user whose illusts are listed. */
+    user: PixivUser;
+    /** Illusts on this page. */
+    illusts: PixivIllustItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/user/novels. */
+interface UserNovelsPage {
+    /** The user whose novels are listed. */
+    user: PixivUser;
+    /** Novels on this page. */
+    novels: PixivNovelItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/user/bookmarks/illust. */
+interface UserBookmarksIllustPage {
+    /** Bookmarked illusts on this page. */
+    illusts: PixivIllustItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/user/bookmarks/novel. */
+interface UserBookmarksNovelPage {
+    /** Bookmarked novels on this page. */
+    novels: PixivNovelItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+/** Page response for GET /v1/user/following. */
+interface UserFollowingPage {
+    /** User preview items on this page. */
+    user_previews: PixivUserPreviewItem[];
+    /** URL to the next page, or `null` when this is the last page. */
+    next_url: string | null;
+}
+
+/**
+ * IllustResource — methods for the illust API namespace.
+ */
+
+/** Parameters for fetching a single illust by ID. */
+interface IllustDetailParams {
+    /** ID of the illust to fetch. */
+    illustId: number;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+}
+/** Parameters for fetching related illusts. */
+interface IllustRelatedParams {
+    /** ID of the illust for which to fetch related works. */
+    illustId: number;
+    /** Additional seed illust IDs to influence recommendations. */
+    seedIllustIds?: number[];
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+}
+/** Parameters for searching illusts. */
+interface IllustSearchParams {
+    /** Search keyword. */
+    word: string;
+    /** How to match the keyword against works (default: `"partial_match_for_tags"`). */
+    searchTarget?: SearchTarget;
+    /** Sort order for results (default: `"date_desc"`). */
+    sort?: SearchSort;
+    /** Date range preset filter (omit for no restriction). */
+    duration?: SearchDuration;
+    /** Start date for a custom date range (YYYY-MM-DD; requires `endDate`). */
+    startDate?: string;
+    /** End date for a custom date range (YYYY-MM-DD; requires `startDate`). */
+    endDate?: string;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** AI-generated content filter: `0` = hide AI works, `1` = show only AI works. */
+    searchAiType?: 0 | 1;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching the illust ranking. */
+interface IllustRankingParams {
+    /** Ranking category (default: `"day"`). */
+    mode?: RankingMode;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Specific date to fetch rankings for (YYYY-MM-DD; omit for the latest). */
+    date?: string;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching recommended illusts. */
+interface IllustRecommendedParams {
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching an illust series. */
+interface IllustSeriesParams {
+    /** ID of the illust series to fetch. */
+    illustSeriesId: number;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+}
+/** Parameters for adding an illust bookmark. */
+interface IllustBookmarkAddParams {
+    /** ID of the illust to bookmark. */
+    illustId: number;
+    /** Bookmark visibility (default: `"public"`). */
+    restrict?: BookmarkRestrict;
+    /** Tags to attach to the bookmark. */
+    tags?: string[];
+}
+/** Parameters for removing an illust bookmark. */
+interface IllustBookmarkDeleteParams {
+    /** ID of the illust to remove from bookmarks. */
+    illustId: number;
+}
+/** Methods for the illust API namespace. */
+declare class IllustResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Fetches a single illust by ID.
+     * GET /v1/illust/detail
+     *
+     * @param params - Request parameters
+     */
+    detail(params: IllustDetailParams): ResultAsync<IllustDetailResponse, PixivError>;
+    /**
+     * Fetches related illusts for a given illust.
+     * GET /v2/illust/related
+     *
+     * @param params - Request parameters
+     */
+    related(params: IllustRelatedParams): PaginatedResultAsync<IllustListPage, IllustListPage['illusts'][number]>;
+    /**
+     * Searches for illusts.
+     * GET /v1/search/illust
+     *
+     * @param params - Request parameters
+     */
+    search(params: IllustSearchParams): PaginatedResultAsync<IllustListPage, IllustListPage['illusts'][number]>;
+    /**
+     * Fetches the illust ranking.
+     * GET /v1/illust/ranking
+     *
+     * @param params - Request parameters
+     */
+    ranking(params?: IllustRankingParams): PaginatedResultAsync<IllustListPage, IllustListPage['illusts'][number]>;
+    /**
+     * Fetches recommended illusts.
+     * GET /v1/illust/recommended
+     *
+     * @param params - Request parameters
+     */
+    recommended(params?: IllustRecommendedParams): PaginatedResultAsync<IllustRecommendedPage, IllustRecommendedPage['illusts'][number]>;
+    /**
+     * Fetches an illust series.
+     * GET /v1/illust/series
+     *
+     * @param params - Request parameters
+     */
+    series(params: IllustSeriesParams): PaginatedResultAsync<IllustSeriesPage, IllustSeriesPage['illusts'][number]>;
+    /**
+     * Adds an illust bookmark.
+     * POST /v2/illust/bookmark/add
+     *
+     * @param params - Request parameters
+     */
+    bookmarkAdd(params: IllustBookmarkAddParams): ResultAsync<Record<string, never>, PixivError>;
+    /**
+     * Removes an illust bookmark.
+     * POST /v1/illust/bookmark/delete
+     *
+     * @param params - Request parameters
+     */
+    bookmarkDelete(params: IllustBookmarkDeleteParams): ResultAsync<Record<string, never>, PixivError>;
+}
+
+/**
+ * NovelResource — methods for the novel API namespace.
+ */
+
+/** Parameters for fetching a single novel by ID. */
+interface NovelDetailParams {
+    /** ID of the novel to fetch. */
+    novelId: number;
+}
+/** Parameters for fetching novel text content. */
+interface NovelTextParams {
+    /** ID of the novel whose text to fetch. */
+    id: number;
+}
+/** Parameters for fetching related novels. */
+interface NovelRelatedParams {
+    /** ID of the novel for which to fetch related works. */
+    novelId: number;
+}
+/** Parameters for searching novels. */
+interface NovelSearchParams {
+    /** Search keyword. */
+    word: string;
+    /** How to match the keyword against works (default: `"partial_match_for_tags"`). */
+    searchTarget?: SearchTarget;
+    /** Sort order for results (default: `"date_desc"`). */
+    sort?: SearchSort;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Date range preset filter (omit for no restriction). */
+    duration?: SearchDuration;
+    /** Start date for a custom date range (YYYY-MM-DD; requires `endDate`). */
+    startDate?: string;
+    /** End date for a custom date range (YYYY-MM-DD; requires `startDate`). */
+    endDate?: string;
+    /** AI-generated content filter: `0` = hide AI works, `1` = show only AI works. */
+    searchAiType?: 0 | 1;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching the novel ranking. */
+interface NovelRankingParams {
+    /** Ranking category (default: `"day"`). */
+    mode?: NovelRankingMode;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Specific date to fetch rankings for (YYYY-MM-DD; omit for the latest). */
+    date?: string;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching recommended novels. */
+interface NovelRecommendedParams {
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching a novel series. */
+interface NovelSeriesParams {
+    /** ID of the novel series to fetch. */
+    seriesId: number;
+    /** Order of the last novel already seen; used for cursor-based pagination. */
+    lastOrder?: number;
+}
+/** Parameters for adding a novel bookmark. */
+interface NovelBookmarkAddParams {
+    /** ID of the novel to bookmark. */
+    novelId: number;
+    /** Bookmark visibility (default: `"public"`). */
+    restrict?: BookmarkRestrict;
+    /** Tags to attach to the bookmark. */
+    tags?: string[];
+}
+/** Parameters for removing a novel bookmark. */
+interface NovelBookmarkDeleteParams {
+    /** ID of the novel to remove from bookmarks. */
+    novelId: number;
+}
+/** Methods for the novel API namespace. */
+declare class NovelResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Fetches a single novel by ID.
+     * GET /v2/novel/detail
+     *
+     * @param params - Request parameters
+     */
+    detail(params: NovelDetailParams): ResultAsync<NovelDetailResponse, PixivError>;
+    /**
+     * Fetches the full text of a novel.
+     * GET /webview/v2/novel
+     *
+     * @param params - Request parameters
+     */
+    text(params: NovelTextParams): ResultAsync<string, PixivError>;
+    /**
+     * Fetches related novels for a given novel.
+     * GET /v1/novel/related
+     *
+     * @param params - Request parameters
+     */
+    related(params: NovelRelatedParams): PaginatedResultAsync<NovelListPage, PixivNovelItem>;
+    /**
+     * Searches for novels.
+     * GET /v1/search/novel
+     *
+     * @param params - Request parameters
+     */
+    search(params: NovelSearchParams): PaginatedResultAsync<NovelListPage, PixivNovelItem>;
+    /**
+     * Fetches the novel ranking.
+     * GET /v1/novel/ranking
+     *
+     * @param params - Request parameters
+     */
+    ranking(params?: NovelRankingParams): PaginatedResultAsync<NovelListPage, PixivNovelItem>;
+    /**
+     * Fetches recommended novels.
+     * GET /v1/novel/recommended
+     *
+     * @param params - Request parameters
+     */
+    recommended(params?: NovelRecommendedParams): PaginatedResultAsync<NovelRecommendedPage, PixivNovelItem>;
+    /**
+     * Fetches a novel series.
+     * GET /v2/novel/series
+     *
+     * @param params - Request parameters
+     */
+    series(params: NovelSeriesParams): PaginatedResultAsync<NovelSeriesPage, PixivNovelItem>;
+    /**
+     * Adds a novel bookmark.
+     * POST /v2/novel/bookmark/add
+     *
+     * @param params - Request parameters
+     */
+    bookmarkAdd(params: NovelBookmarkAddParams): ResultAsync<Record<string, never>, PixivError>;
+    /**
+     * Removes a novel bookmark.
+     * POST /v1/novel/bookmark/delete
+     *
+     * @param params - Request parameters
+     */
+    bookmarkDelete(params: NovelBookmarkDeleteParams): ResultAsync<Record<string, never>, PixivError>;
+}
+
+/**
+ * UserResource — methods for the user API namespace.
+ */
+
+/** Parameters for fetching a user's bookmarked illusts. */
+interface UserBookmarksIllustParams {
+    /** ID of the user whose bookmarks to fetch. */
+    userId: number;
+    /** Visibility of the bookmarks to return (default: `"public"`). */
+    restrict?: BookmarkRestrict;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Limit results to bookmarks with this tag. */
+    tag?: string;
+    /** Fetch bookmarks older than this bookmark ID (cursor-based pagination). */
+    maxBookmarkId?: number;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching a user's bookmarked novels. */
+interface UserBookmarksNovelParams {
+    /** ID of the user whose bookmarks to fetch. */
+    userId: number;
+    /** Visibility of the bookmarks to return (default: `"public"`). */
+    restrict?: BookmarkRestrict;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Limit results to bookmarks with this tag. */
+    tag?: string;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching a user's detail. */
+interface UserDetailParams {
+    /** ID of the user to fetch. */
+    userId: number;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+}
+/** Parameters for fetching a user's illusts. */
+interface UserIllustsParams {
+    /** ID of the user whose illusts to fetch. */
+    userId: number;
+    /** Work type to filter by (omit to return both illusts and manga). */
+    type?: UserIllustType;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching a user's novels. */
+interface UserNovelsParams {
+    /** ID of the user whose novels to fetch. */
+    userId: number;
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for fetching a user's following list. */
+interface UserFollowingParams {
+    /** ID of the user whose following list to fetch. */
+    userId: number;
+    /** Visibility of the follows to return (default: `"public"`). */
+    restrict?: FollowRestrict;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Parameters for following a user. */
+interface UserFollowAddParams {
+    /** ID of the user to follow. */
+    userId: number;
+    /** Visibility of the follow (default: `"public"`). */
+    restrict?: FollowRestrict;
+}
+/** Parameters for unfollowing a user. */
+interface UserFollowDeleteParams {
+    /** ID of the user to unfollow. */
+    userId: number;
+}
+/** Methods for the user bookmarks sub-namespace. */
+declare class UserBookmarksResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Fetches a user's bookmarked illusts.
+     * GET /v1/user/bookmarks/illust
+     *
+     * @param params - Request parameters
+     */
+    illusts(params: UserBookmarksIllustParams): PaginatedResultAsync<UserBookmarksIllustPage, PixivIllustItem>;
+    /**
+     * Fetches a user's bookmarked novels.
+     * GET /v1/user/bookmarks/novel
+     *
+     * @param params - Request parameters
+     */
+    novels(params: UserBookmarksNovelParams): PaginatedResultAsync<UserBookmarksNovelPage, PixivNovelItem>;
+}
+/** Methods for the user API namespace. */
+declare class UserResource {
+    #private;
+    /** User bookmarks sub-namespace. */
+    readonly bookmarks: UserBookmarksResource;
+    constructor(http: HttpClient);
+    /**
+     * Fetches detailed profile information for a user.
+     * GET /v1/user/detail
+     *
+     * @param params - Request parameters
+     */
+    detail(params: UserDetailParams): ResultAsync<UserDetailResponse, PixivError>;
+    /**
+     * Fetches illusts posted by a user.
+     * GET /v1/user/illusts
+     *
+     * @param params - Request parameters
+     */
+    illusts(params: UserIllustsParams): PaginatedResultAsync<UserIllustsPage, PixivIllustItem>;
+    /**
+     * Fetches novels posted by a user.
+     * GET /v1/user/novels
+     *
+     * @param params - Request parameters
+     */
+    novels(params: UserNovelsParams): PaginatedResultAsync<UserNovelsPage, PixivNovelItem>;
+    /**
+     * Fetches the list of users that a user is following.
+     * GET /v1/user/following
+     *
+     * @param params - Request parameters
+     */
+    following(params: UserFollowingParams): PaginatedResultAsync<UserFollowingPage, PixivUserPreviewItem>;
+    /**
+     * Follows a user.
+     * POST /v1/user/follow/add
+     *
+     * @param params - Request parameters
+     */
+    followAdd(params: UserFollowAddParams): ResultAsync<Record<string, never>, PixivError>;
+    /**
+     * Unfollows a user.
+     * POST /v1/user/follow/delete
+     *
+     * @param params - Request parameters
+     */
+    followDelete(params: UserFollowDeleteParams): ResultAsync<Record<string, never>, PixivError>;
+}
+
+/**
+ * MangaResource — methods for the manga API namespace.
+ */
+
+/** Parameters for fetching recommended manga. */
+interface MangaRecommendedParams {
+    /** OS filter to apply (default: `"for_ios"`). */
+    filter?: OSFilter;
+    /** Zero-based offset for pagination. */
+    offset?: number;
+}
+/** Methods for the manga API namespace. */
+declare class MangaResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Fetches recommended manga.
+     * GET /v1/manga/recommended
+     *
+     * @param params - Request parameters
+     */
+    recommended(params?: MangaRecommendedParams): PaginatedResultAsync<MangaRecommendedPage, PixivIllustItem>;
+}
+
+/**
+ * UgoiraResource — methods for the ugoira API namespace.
+ */
+
+/** Parameters for fetching ugoira metadata. */
+interface UgoiraMetadataParams {
+    /** ID of the ugoira illust whose metadata to fetch. */
+    illustId: number;
+}
+/** Methods for the ugoira API namespace. */
+declare class UgoiraResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Fetches ugoira metadata (ZIP URL and per-frame timings).
+     * GET /v1/ugoira/metadata
+     *
+     * @param params - Request parameters
+     */
+    metadata(params: UgoiraMetadataParams): ResultAsync<UgoiraMetadataResponse, PixivError>;
+}
+
+/**
+ * ImageResource — helpers for fetching pixiv CDN images.
+ */
+
+/** Methods for fetching pixiv images. */
+declare class ImageResource {
+    #private;
+    constructor(http: HttpClient);
+    /**
+     * Fetches a pixiv image.
+     *
+     * Uses a browser User-Agent and Referer (required for pixiv CDN).
+     * No Authorization header is sent.
+     *
+     * @param imageUrl - Full CDN image URL
+     */
+    fetch(imageUrl: string): ResultAsync<Response, PixivError>;
+}
+
+/**
+ * PixivClient — main entry point for the @book000/pixivts library.
+ *
+ * @example
+ * ```ts
+ * const client = await PixivClient.of(process.env.PIXIV_REFRESH_TOKEN!)
+ * const result = await client.illusts.detail({ illustId: 12345 })
+ * if (result.isOk) console.log(result.value.illust.title)
+ * ```
+ */
+
+/** Options for constructing a {@link PixivClient}. */
+interface PixivClientOptions {
+    /** Rate-limit retry configuration. */
+    retry?: Partial<RateLimitRetryOptions>;
+    /** Optional interceptor called after each successful response (DB seam). */
+    onResponse?: ResponseInterceptor;
+}
+/**
+ * Main client for the pixiv API.
+ *
+ * Create an instance via {@link PixivClient.of} — the constructor is private
+ * because initialisation requires an async token refresh.
+ */
+declare class PixivClient {
+    #private;
+    /** Illust API namespace. */
+    readonly illusts: IllustResource;
+    /** Novel API namespace. */
+    readonly novels: NovelResource;
+    /** User API namespace. */
+    readonly users: UserResource;
+    /** Manga API namespace. */
+    readonly manga: MangaResource;
+    /** Ugoira API namespace. */
+    readonly ugoira: UgoiraResource;
+    /** Image fetch helpers. */
+    readonly images: ImageResource;
+    private constructor();
+    /**
+     * Numeric user ID of the authenticated account, as a string.
+     *
+     * Available immediately after {@link PixivClient.of} resolves.
+     */
+    get userId(): string;
+    /**
+     * Creates a PixivClient by refreshing the given token.
+     *
+     * @param refreshToken - Pixiv refresh token
+     * @param options - Optional retry and response interceptor configuration
+     * @returns A fully initialised {@link PixivClient}
+     */
+    static of(refreshToken: string, options?: PixivClientOptions): Promise<PixivClient>;
+}
+
+export { type BookmarkRestrict, type ErrResult, type FollowRestrict, type Frame, type HttpMethod, type IllustBookmarkAddParams, type IllustBookmarkDeleteParams, type IllustDetailParams, type IllustDetailResponse, type IllustListPage, type IllustRankingParams, type IllustRecommendedPage, type IllustRecommendedParams, type IllustRelatedParams, type IllustSearchParams, type IllustSeriesDetail, type IllustSeriesPage, type IllustSeriesParams, type ImageUrls, type MangaRecommendedPage, type MetaPages, type MetaSinglePage, type NovelBookmarkAddParams, type NovelBookmarkDeleteParams, type NovelDetailParams, type NovelDetailResponse, type NovelListPage, type NovelRankingMode, type NovelRankingParams, type NovelRecommendedPage, type NovelRecommendedParams, type NovelRelatedParams, type NovelSearchParams, type NovelSeriesDetail, type NovelSeriesPage, type NovelSeriesParams, type NovelTextParams, type OSFilter, type OkResult, type PagedResponse, PaginatedResultAsync, type PixivApiErrorBody, PixivClient, type PixivClientOptions, type PixivError, PixivFetchError, type PixivIllustItem, type PixivNovelItem, type PixivUgoiraItem, type PixivUser, type PixivUserItem, type PixivUserPreviewItem, type PixivUserProfile, type PixivUserProfilePublicity, type PixivUserProfileWorkspace, type PrivacyPolicy, type ProfileImageUrls, type RankingMode, type ResponseInterceptor, type ResponseRecord, type Result, ResultAsync, type SearchDuration, type SearchSort, type SearchTarget, type Series, type Tag, type UgoiraMetadataResponse, type UserBookmarksIllustPage, type UserBookmarksIllustParams, type UserBookmarksNovelPage, type UserBookmarksNovelParams, type UserDetailParams, type UserDetailResponse, type UserFollowAddParams, type UserFollowDeleteParams, type UserFollowingPage, type UserFollowingParams, type UserIllustType, type UserIllustsPage, type UserIllustsParams, type UserNovelsPage, type UserNovelsParams, type ZipUrls, apiError, authFailedError, err, failedPaginated, networkError, ok, rateLimitError };