@book000/pixivts 0.55.1 → 0.56.1

package/dist/index.cjs

@@ -0,0 +1,1321 @@
+'use strict';
+
+// src/result.ts
+var OkResultImpl = class _OkResultImpl {
+  constructor(value) {
+    this.value = value;
+  }
+  isOk = true;
+  isErr = false;
+  map(fn) {
+    return new _OkResultImpl(fn(this.value));
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters, @typescript-eslint/no-unused-vars -- F is part of the public API contract; _fn is intentionally unused (OkResult.mapErr is a no-op)
+  mapErr(_fn) {
+    return this;
+  }
+  andThen(fn) {
+    return fn(this.value);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- _onErr is intentionally unused: OkResult.match always calls onOk
+  match(onOk, _onErr) {
+    return onOk(this.value);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- _fallback is intentionally unused: OkResult.unwrapOr always returns value
+  unwrapOr(_fallback) {
+    return this.value;
+  }
+};
+var ErrResultImpl = class _ErrResultImpl {
+  // eslint-disable-next-line n/handle-callback-err -- 'error' is a stored value, not a Node.js callback error parameter
+  constructor(error) {
+    this.error = error;
+  }
+  isOk = false;
+  isErr = true;
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters, @typescript-eslint/no-unused-vars -- U is part of the public API contract; _fn is intentionally unused (ErrResult.map is a no-op)
+  map(_fn) {
+    return this;
+  }
+  mapErr(fn) {
+    return new _ErrResultImpl(fn(this.error));
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- _fn is intentionally unused: ErrResult.andThen is a no-op (the success path does not apply)
+  andThen(_fn) {
+    return this;
+  }
+  match(_onOk, onErr) {
+    return onErr(this.error);
+  }
+  unwrapOr(fallback) {
+    return fallback;
+  }
+};
+function ok(value) {
+  return new OkResultImpl(value);
+}
+function err(error) {
+  return new ErrResultImpl(error);
+}
+var ResultAsync = class _ResultAsync {
+  _promise;
+  constructor(promise) {
+    this._promise = promise;
+  }
+  // PromiseLike contract — makes `await resultAsync` work
+  // eslint-disable-next-line unicorn/no-thenable -- ResultAsync intentionally implements PromiseLike to be directly awaitable
+  then(onfulfilled, onrejected) {
+    return this._promise.then(onfulfilled, onrejected);
+  }
+  /**
+   * 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(promise, onError) {
+    return new _ResultAsync(
+      promise.then(
+        (v) => ok(v),
+        (error) => err(onError(error))
+      )
+    );
+  }
+  /**
+   * Wraps an already-resolved `Result<T, E>` into a `ResultAsync<T, E>`.
+   *
+   * @param result - The result to wrap
+   */
+  static fromResult(result) {
+    return new _ResultAsync(Promise.resolve(result));
+  }
+  /**
+   * Transforms the success value.
+   *
+   * If the inner result is `Err`, `fn` is not called.
+   *
+   * @param fn - Synchronous mapper
+   */
+  map(fn) {
+    return new _ResultAsync(
+      // eslint-disable-next-line unicorn/no-array-callback-reference -- r.map(fn) is safe here; fn is a user-supplied mapper, not a DOM/Array method reference
+      this._promise.then((r) => r.map(fn))
+    );
+  }
+  /**
+   * Transforms the error value.
+   *
+   * If the inner result is `Ok`, `fn` is not called.
+   *
+   * @param fn - Synchronous error mapper
+   */
+  mapErr(fn) {
+    return new _ResultAsync(
+      this._promise.then((r) => r.mapErr(fn))
+    );
+  }
+  /**
+   * 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(fn) {
+    return new _ResultAsync(
+      this._promise.then(async (r) => {
+        if (r.isErr) return r;
+        const next = fn(r.value);
+        if (next instanceof _ResultAsync) {
+          return next._promise;
+        }
+        return next;
+      })
+    );
+  }
+  /**
+   * Pattern-matches on success / failure.
+   *
+   * @param onOk - Called with the success value
+   * @param onErr - Called with the error value
+   * @returns A `Promise<U>`
+   */
+  async match(onOk, onErr) {
+    const r = await this._promise;
+    if (r.isOk) return onOk(r.value);
+    return onErr(r.error);
+  }
+  /**
+   * Returns the success value, or `fallback` if the result is `Err`.
+   *
+   * @param fallback - The fallback value
+   */
+  async unwrapOr(fallback) {
+    const r = await this._promise;
+    if (r.isOk) return r.value;
+    return fallback;
+  }
+};
+
+// src/errors.ts
+var PixivFetchError = class extends Error {
+  /** The underlying structured `PixivError`. */
+  pixivError;
+  constructor(pixivError) {
+    super(`pixiv API error: ${pixivError.type}`);
+    this.name = "PixivFetchError";
+    this.pixivError = pixivError;
+    Object.assign(this, pixivError);
+  }
+};
+function rateLimitError(retryAfter) {
+  return { type: "rate_limit", retryAfter };
+}
+function authFailedError(status) {
+  return { type: "auth_failed", status };
+}
+function networkError(cause) {
+  return { type: "network", cause };
+}
+function apiError(status, body) {
+  return { type: "api_error", status, body };
+}
+
+// src/paginated.ts
+var PaginatedResultAsync = class _PaginatedResultAsync extends ResultAsync {
+  #http;
+  #getItems;
+  constructor(promise, http, getItems) {
+    super(promise);
+    this.#http = http;
+    this.#getItems = getItems;
+  }
+  /**
+   * 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(inner, http, getItems) {
+    const promise = Promise.resolve(inner);
+    return new _PaginatedResultAsync(promise, http, getItems);
+  }
+  /**
+   * 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)
+   * }
+   * ```
+   */
+  async *pages() {
+    const first = await Promise.resolve(this);
+    if (first.isErr) throw new PixivFetchError(first.error);
+    yield first.value;
+    let nextUrl = first.value.next_url;
+    while (nextUrl !== null) {
+      const pageResult = await this.#http.getAbsolute(nextUrl);
+      if (pageResult.isErr) throw new PixivFetchError(pageResult.error);
+      yield pageResult.value;
+      nextUrl = pageResult.value.next_url;
+    }
+  }
+  /**
+   * 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)
+   * }
+   * ```
+   */
+  async *items() {
+    for await (const page of this.pages()) {
+      for (const item of this.#getItems(page)) {
+        yield item;
+      }
+    }
+  }
+};
+function failedPaginated(error, http, getItems) {
+  return new PaginatedResultAsync(
+    Promise.resolve(err(error)),
+    http,
+    getItems
+  );
+}
+
+// src/auth.ts
+var T = Array.from(
+  { length: 64 },
+  (_, i) => Math.floor(Math.abs(Math.sin(i + 1)) * 2 ** 32)
+);
+var S = [
+  7,
+  12,
+  17,
+  22,
+  7,
+  12,
+  17,
+  22,
+  7,
+  12,
+  17,
+  22,
+  7,
+  12,
+  17,
+  22,
+  5,
+  9,
+  14,
+  20,
+  5,
+  9,
+  14,
+  20,
+  5,
+  9,
+  14,
+  20,
+  5,
+  9,
+  14,
+  20,
+  4,
+  11,
+  16,
+  23,
+  4,
+  11,
+  16,
+  23,
+  4,
+  11,
+  16,
+  23,
+  4,
+  11,
+  16,
+  23,
+  6,
+  10,
+  15,
+  21,
+  6,
+  10,
+  15,
+  21,
+  6,
+  10,
+  15,
+  21,
+  6,
+  10,
+  15,
+  21
+];
+function md5Bytes(bytes) {
+  const len = bytes.length;
+  bytes.push(128);
+  while (bytes.length % 64 !== 56) bytes.push(0);
+  const bitLen = len * 8;
+  for (let i = 0; i < 8; i++) {
+    bytes.push(i < 4 ? bitLen >>> i * 8 & 255 : 0);
+  }
+  let a = 1732584193;
+  let b = 4023233417;
+  let c = 2562383102;
+  let d = 271733878;
+  for (let chunk = 0; chunk < bytes.length; chunk += 64) {
+    const M = [];
+    for (let w = 0; w < 16; w++) {
+      const off = chunk + w * 4;
+      M.push(
+        bytes[off] | bytes[off + 1] << 8 | bytes[off + 2] << 16 | bytes[off + 3] << 24
+      );
+    }
+    let aa = a;
+    let bb = b;
+    let cc = c;
+    let dd = d;
+    for (let i = 0; i < 64; i++) {
+      let f;
+      let g;
+      if (i < 16) {
+        f = bb & cc | ~bb & dd;
+        g = i;
+      } else if (i < 32) {
+        f = dd & bb | ~dd & cc;
+        g = (5 * i + 1) % 16;
+      } else if (i < 48) {
+        f = bb ^ cc ^ dd;
+        g = (3 * i + 5) % 16;
+      } else {
+        f = cc ^ (bb | ~dd);
+        g = 7 * i % 16;
+      }
+      const tmp = dd;
+      dd = cc;
+      cc = bb;
+      const sum = Math.trunc(aa + f + M[g] + T[i]);
+      const rotated = sum << S[i] | sum >>> 32 - S[i];
+      bb = Math.trunc(bb + rotated);
+      aa = tmp;
+    }
+    a = Math.trunc(a + aa);
+    b = Math.trunc(b + bb);
+    c = Math.trunc(c + cc);
+    d = Math.trunc(d + dd);
+  }
+  return [a, b, c, d].map(
+    (n) => [n & 255, n >>> 8 & 255, n >>> 16 & 255, n >>> 24 & 255].map((byte) => byte.toString(16).padStart(2, "0")).join("")
+  ).join("");
+}
+function md5(input) {
+  const bytes = [];
+  for (let i = 0; i < input.length; i++) {
+    const code = input.codePointAt(i) ?? 0;
+    if (code < 128) {
+      bytes.push(code);
+    } else if (code < 2048) {
+      bytes.push(192 | code >> 6, 128 | code & 63);
+    } else {
+      bytes.push(
+        224 | code >> 12,
+        128 | code >> 6 & 63,
+        128 | code & 63
+      );
+    }
+  }
+  return md5Bytes(bytes);
+}
+var CLIENT_ID = "MOBrBDS8blbauoSck0ZfDbtuzpyT";
+var CLIENT_SECRET = "lsACyCD94FhDUtGTXi3QzcFE2uU1hqtDaKeqrdwj";
+var HASH_SECRET = "28c1fdd170a5204386cb1313c7077b34f83e4aaf4aa829ce78c231e05b0bae2c";
+var AUTH_URL = "https://oauth.secure.pixiv.net/auth/token";
+function buildClientHash(localTime) {
+  return md5(localTime + HASH_SECRET);
+}
+var AuthManager = class _AuthManager {
+  #accessToken;
+  #refreshToken;
+  userId;
+  constructor(credentials) {
+    this.#accessToken = credentials.accessToken;
+    this.#refreshToken = credentials.refreshToken;
+    this.userId = credentials.userId;
+  }
+  /** Returns the current access token. */
+  get accessToken() {
+    return this.#accessToken;
+  }
+  /** Returns the current refresh token. */
+  get refreshToken() {
+    return this.#refreshToken;
+  }
+  /**
+   * 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.
+   */
+  async refresh() {
+    const localTime = (/* @__PURE__ */ new Date()).toISOString().replace(/Z$/, "+00:00");
+    const headers = {
+      "x-client-time": localTime,
+      "x-client-hash": buildClientHash(localTime),
+      "app-os": "ios",
+      "app-os-version": "16.4.1",
+      "user-agent": "PixivIOSApp/7.16.9 (iOS 16.4.1; iPad13,4)",
+      "Content-Type": "application/x-www-form-urlencoded"
+    };
+    const body = new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      get_secure_url: "1",
+      grant_type: "refresh_token",
+      refresh_token: this.#refreshToken
+    }).toString();
+    const response = await fetch(AUTH_URL, {
+      method: "POST",
+      headers,
+      body
+    });
+    if (response.status !== 200) {
+      throw new Error(
+        `Failed to refresh pixiv token: HTTP ${response.status}`
+      );
+    }
+    const data = await response.json();
+    this.#accessToken = data.response.access_token;
+    this.#refreshToken = data.response.refresh_token;
+    this.userId = data.user.id;
+  }
+  /**
+   * Creates an `AuthManager` by performing the initial token refresh.
+   *
+   * @param refreshToken - Pixiv refresh token
+   * @returns Initialized `AuthManager`
+   */
+  static async login(refreshToken) {
+    const manager = new _AuthManager({
+      userId: "",
+      accessToken: "",
+      refreshToken
+    });
+    await manager.refresh();
+    return manager;
+  }
+};
+
+// src/http.ts
+var DEFAULT_RETRY = { maxRetries: 3, waitMs: 1e4 };
+var BASE_URL = "https://app-api.pixiv.net";
+var DEFAULT_HEADERS = {
+  Host: "app-api.pixiv.net",
+  "App-OS": "ios",
+  "App-OS-Version": "14.6",
+  "User-Agent": "PixivIOSApp/7.13.3 (iOS 14.6; iPhone13,2)",
+  "Accept-Language": "ja"
+};
+function parseRetryAfter(retryAfter, defaultMs) {
+  if (!retryAfter) return defaultMs;
+  if (/^\d+$/.test(retryAfter.trim())) {
+    return Number.parseInt(retryAfter, 10) * 1e3;
+  }
+  const retryDate = Date.parse(retryAfter);
+  if (!Number.isNaN(retryDate)) {
+    return Math.max(0, retryDate - Date.now());
+  }
+  return defaultMs;
+}
+function headersToRecord(headers) {
+  const result = {};
+  for (const [key, value] of headers) {
+    result[key] = value;
+  }
+  return result;
+}
+var HttpClient = class {
+  #auth;
+  #retry;
+  #interceptor;
+  constructor(auth, options) {
+    this.#auth = auth;
+    this.#retry = {
+      maxRetries: options?.retry?.maxRetries ?? DEFAULT_RETRY.maxRetries,
+      waitMs: options?.retry?.waitMs ?? DEFAULT_RETRY.waitMs
+    };
+    this.#interceptor = options?.onResponse;
+  }
+  /**
+   * 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(path, params) {
+    const qs = params ? `?${params.toString()}` : "";
+    const url = `${BASE_URL}${path}${qs}`;
+    return this.#send(url, "GET", path, void 0);
+  }
+  /**
+   * 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(path, body) {
+    const url = `${BASE_URL}${path}`;
+    return this.#send(url, "POST", path, body);
+  }
+  /**
+   * 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) {
+    return ResultAsync.fromPromise(
+      fetch(imageUrl, {
+        headers: {
+          "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
+          Referer: "https://www.pixiv.net/"
+        }
+      }),
+      networkError
+    ).andThen((response) => {
+      if (!response.ok) {
+        return ResultAsync.fromResult(
+          err(apiError(response.status, null))
+        );
+      }
+      return ResultAsync.fromResult(ok(response));
+    });
+  }
+  /**
+   * 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(absoluteUrl) {
+    let endpoint;
+    try {
+      endpoint = new URL(absoluteUrl).pathname;
+    } catch {
+      endpoint = absoluteUrl;
+    }
+    return this.#send(absoluteUrl, "GET", endpoint, void 0);
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  #send(url, method, endpoint, body) {
+    return new ResultAsync(this.#sendWithRetry(url, method, endpoint, body));
+  }
+  async #sendWithRetry(url, method, endpoint, body, allowRefresh = true) {
+    const maxRetries = Math.max(0, this.#retry.maxRetries);
+    const waitMs = Math.max(0, this.#retry.waitMs);
+    let lastRetryAfterMs = 0;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      const requestHeaders = {
+        ...DEFAULT_HEADERS,
+        Authorization: `Bearer ${this.#auth.accessToken}`,
+        ...method === "POST" ? { "Content-Type": "application/x-www-form-urlencoded" } : {}
+      };
+      let response;
+      try {
+        response = await fetch(url, {
+          method,
+          headers: requestHeaders,
+          body: method === "POST" ? body : void 0
+        });
+      } catch (fetchError) {
+        return err(networkError(fetchError));
+      }
+      if (response.status === 429) {
+        await response.body?.cancel();
+        const retryAfterMs = parseRetryAfter(
+          response.headers.get("Retry-After"),
+          waitMs
+        );
+        lastRetryAfterMs = retryAfterMs;
+        if (attempt < maxRetries) {
+          await new Promise((resolve) => setTimeout(resolve, retryAfterMs));
+          continue;
+        }
+        return err(rateLimitError(lastRetryAfterMs));
+      }
+      if (response.status === 401) {
+        await response.body?.cancel();
+        if (allowRefresh) {
+          try {
+            await this.#auth.refresh();
+          } catch {
+            return err(authFailedError(401));
+          }
+          return this.#sendWithRetry(url, method, endpoint, body, false);
+        }
+        return err(authFailedError(401));
+      }
+      const contentType = response.headers.get("content-type") ?? "";
+      const text = await response.text();
+      let data;
+      const isJson = contentType.includes("application/json");
+      if (isJson) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      } else {
+        data = text;
+      }
+      const responseHeaders = headersToRecord(response.headers);
+      if (!response.ok) {
+        return err(apiError(response.status, data));
+      }
+      const httpResponse = {
+        data,
+        status: response.status,
+        responseUrl: response.url || void 0};
+      if (this.#interceptor) {
+        const record = {
+          method,
+          endpoint,
+          url: response.url || url,
+          requestHeaders: JSON.stringify(requestHeaders),
+          requestBody: body ?? null,
+          responseType: isJson ? "JSON" : "TEXT",
+          statusCode: response.status,
+          responseHeaders: JSON.stringify(responseHeaders),
+          responseBody: isJson ? JSON.stringify(data) : text
+        };
+        Promise.resolve(this.#interceptor(record)).catch(() => void 0);
+      }
+      return ok(httpResponse.data);
+    }
+    return err(rateLimitError(lastRetryAfterMs));
+  }
+};
+
+// src/params.ts
+function camelToSnake(key) {
+  return key.replaceAll(/([A-Z])/g, (m) => `_${m.toLowerCase()}`);
+}
+function toSnakeKeys(obj) {
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    out[camelToSnake(key)] = obj[key];
+  }
+  return out;
+}
+function buildSearchParams(params) {
+  const usp = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === null || value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) usp.append(key, String(item));
+    } else {
+      usp.set(key, String(value));
+    }
+  }
+  return usp;
+}
+function buildParams(params) {
+  return buildSearchParams(toSnakeKeys(params));
+}
+
+// src/resources/illusts.ts
+var IllustResource = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Fetches a single illust by ID.
+   * GET /v1/illust/detail
+   *
+   * @param params - Request parameters
+   */
+  detail(params) {
+    return this.#http.get(
+      "/v1/illust/detail",
+      buildParams({ illustId: params.illustId, filter: params.filter ?? "for_ios" })
+    );
+  }
+  /**
+   * Fetches related illusts for a given illust.
+   * GET /v2/illust/related
+   *
+   * @param params - Request parameters
+   */
+  related(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v2/illust/related",
+        buildParams({
+          illustId: params.illustId,
+          filter: params.filter ?? "for_ios",
+          ...params.seedIllustIds ? { seedIllustIds: params.seedIllustIds } : {}
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Searches for illusts.
+   * GET /v1/search/illust
+   *
+   * @param params - Request parameters
+   */
+  search(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/search/illust",
+        buildParams({
+          word: params.word,
+          searchTarget: params.searchTarget ?? "partial_match_for_tags",
+          sort: params.sort ?? "date_desc",
+          filter: params.filter ?? "for_ios",
+          duration: params.duration,
+          startDate: params.startDate,
+          endDate: params.endDate,
+          searchAiType: params.searchAiType,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Fetches the illust ranking.
+   * GET /v1/illust/ranking
+   *
+   * @param params - Request parameters
+   */
+  ranking(params = {}) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/illust/ranking",
+        buildParams({
+          mode: params.mode ?? "day",
+          filter: params.filter ?? "for_ios",
+          date: params.date,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Fetches recommended illusts.
+   * GET /v1/illust/recommended
+   *
+   * @param params - Request parameters
+   */
+  recommended(params = {}) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/illust/recommended",
+        buildParams({
+          filter: params.filter ?? "for_ios",
+          includeRankingLabel: true,
+          includeRankingIllusts: true,
+          includePrivacyPolicy: true,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Fetches an illust series.
+   * GET /v1/illust/series
+   *
+   * @param params - Request parameters
+   */
+  series(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/illust/series",
+        buildParams({
+          illustSeriesId: params.illustSeriesId,
+          filter: params.filter ?? "for_ios"
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Adds an illust bookmark.
+   * POST /v2/illust/bookmark/add
+   *
+   * @param params - Request parameters
+   */
+  bookmarkAdd(params) {
+    const body = buildParams({
+      illustId: params.illustId,
+      restrict: params.restrict ?? "public",
+      ...params.tags ? { tags: params.tags } : {}
+    });
+    return this.#http.post(
+      "/v2/illust/bookmark/add",
+      body.toString()
+    );
+  }
+  /**
+   * Removes an illust bookmark.
+   * POST /v1/illust/bookmark/delete
+   *
+   * @param params - Request parameters
+   */
+  bookmarkDelete(params) {
+    const body = buildParams({ illustId: String(params.illustId) });
+    return this.#http.post(
+      "/v1/illust/bookmark/delete",
+      body.toString()
+    );
+  }
+};
+
+// src/resources/novels.ts
+var NovelResource = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Fetches a single novel by ID.
+   * GET /v2/novel/detail
+   *
+   * @param params - Request parameters
+   */
+  detail(params) {
+    return this.#http.get(
+      "/v2/novel/detail",
+      buildParams({ novelId: params.novelId })
+    );
+  }
+  /**
+   * Fetches the WebView HTML for a novel.
+   * GET /webview/v2/novel
+   *
+   * Returns the raw HTML page that the pixiv app renders in a WebView.
+   * To extract the plain text, parse the returned HTML (e.g. strip tags).
+   *
+   * @param params - Request parameters
+   */
+  text(params) {
+    return this.#http.get(
+      "/webview/v2/novel",
+      // The webview endpoint uses the query parameter 'id', not 'novel_id'
+      buildParams({ id: params.novelId })
+    );
+  }
+  /**
+   * Fetches related novels for a given novel.
+   * GET /v1/novel/related
+   *
+   * @param params - Request parameters
+   */
+  related(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/novel/related",
+        buildParams({ novelId: params.novelId })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+  /**
+   * Searches for novels.
+   * GET /v1/search/novel
+   *
+   * @param params - Request parameters
+   */
+  search(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/search/novel",
+        buildParams({
+          word: params.word,
+          searchTarget: params.searchTarget ?? "partial_match_for_tags",
+          sort: params.sort ?? "date_desc",
+          filter: params.filter ?? "for_ios",
+          duration: params.duration,
+          startDate: params.startDate,
+          endDate: params.endDate,
+          searchAiType: params.searchAiType,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+  /**
+   * Fetches the novel ranking.
+   * GET /v1/novel/ranking
+   *
+   * @param params - Request parameters
+   */
+  ranking(params = {}) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/novel/ranking",
+        buildParams({
+          mode: params.mode ?? "day",
+          filter: params.filter ?? "for_ios",
+          date: params.date,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+  /**
+   * Fetches recommended novels.
+   * GET /v1/novel/recommended
+   *
+   * @param params - Request parameters
+   */
+  recommended(params = {}) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/novel/recommended",
+        buildParams({
+          filter: params.filter ?? "for_ios",
+          includeRankingNovels: true,
+          includePrivacyPolicy: true,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+  /**
+   * Fetches a novel series.
+   * GET /v2/novel/series
+   *
+   * @param params - Request parameters
+   */
+  series(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v2/novel/series",
+        buildParams({ seriesId: params.seriesId, lastOrder: params.lastOrder })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+  /**
+   * Adds a novel bookmark.
+   * POST /v2/novel/bookmark/add
+   *
+   * @param params - Request parameters
+   */
+  bookmarkAdd(params) {
+    const body = buildParams({
+      novelId: params.novelId,
+      restrict: params.restrict ?? "public",
+      ...params.tags ? { tags: params.tags } : {}
+    });
+    return this.#http.post(
+      "/v2/novel/bookmark/add",
+      body.toString()
+    );
+  }
+  /**
+   * Removes a novel bookmark.
+   * POST /v1/novel/bookmark/delete
+   *
+   * @param params - Request parameters
+   */
+  bookmarkDelete(params) {
+    const body = buildParams({ novelId: String(params.novelId) });
+    return this.#http.post(
+      "/v1/novel/bookmark/delete",
+      body.toString()
+    );
+  }
+};
+
+// src/resources/users.ts
+var UserBookmarksResource = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Fetches a user's bookmarked illusts.
+   * GET /v1/user/bookmarks/illust
+   *
+   * @param params - Request parameters
+   */
+  illusts(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/user/bookmarks/illust",
+        buildParams({
+          userId: params.userId,
+          restrict: params.restrict ?? "public",
+          filter: params.filter ?? "for_ios",
+          tag: params.tag,
+          maxBookmarkId: params.maxBookmarkId,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Fetches a user's bookmarked novels.
+   * GET /v1/user/bookmarks/novel
+   *
+   * @param params - Request parameters
+   */
+  novels(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/user/bookmarks/novel",
+        buildParams({
+          userId: params.userId,
+          restrict: params.restrict ?? "public",
+          filter: params.filter ?? "for_ios",
+          tag: params.tag,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+};
+var UserResource = class {
+  /** User bookmarks sub-namespace. */
+  bookmarks;
+  #http;
+  constructor(http) {
+    this.#http = http;
+    this.bookmarks = new UserBookmarksResource(http);
+  }
+  /**
+   * Fetches detailed profile information for a user.
+   * GET /v1/user/detail
+   *
+   * @param params - Request parameters
+   */
+  detail(params) {
+    return this.#http.get(
+      "/v1/user/detail",
+      buildParams({ userId: params.userId, filter: params.filter ?? "for_ios" })
+    );
+  }
+  /**
+   * Fetches illusts posted by a user.
+   * GET /v1/user/illusts
+   *
+   * @param params - Request parameters
+   */
+  illusts(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/user/illusts",
+        buildParams({
+          userId: params.userId,
+          type: params.type,
+          filter: params.filter ?? "for_ios",
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+  /**
+   * Fetches novels posted by a user.
+   * GET /v1/user/novels
+   *
+   * @param params - Request parameters
+   */
+  novels(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/user/novels",
+        buildParams({
+          userId: params.userId,
+          filter: params.filter ?? "for_ios",
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.novels
+    );
+  }
+  /**
+   * Fetches the list of users that a user is following.
+   * GET /v1/user/following
+   *
+   * @param params - Request parameters
+   */
+  following(params) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/user/following",
+        buildParams({
+          userId: params.userId,
+          restrict: params.restrict ?? "public",
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.user_previews
+    );
+  }
+  /**
+   * Follows a user.
+   * POST /v1/user/follow/add
+   *
+   * @param params - Request parameters
+   */
+  followAdd(params) {
+    const body = buildParams({
+      userId: params.userId,
+      restrict: params.restrict ?? "public"
+    });
+    return this.#http.post(
+      "/v1/user/follow/add",
+      body.toString()
+    );
+  }
+  /**
+   * Unfollows a user.
+   * POST /v1/user/follow/delete
+   *
+   * @param params - Request parameters
+   */
+  followDelete(params) {
+    const body = buildParams({ userId: String(params.userId) });
+    return this.#http.post(
+      "/v1/user/follow/delete",
+      body.toString()
+    );
+  }
+};
+
+// src/resources/manga.ts
+var MangaResource = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Fetches recommended manga.
+   * GET /v1/manga/recommended
+   *
+   * @param params - Request parameters
+   */
+  recommended(params = {}) {
+    return PaginatedResultAsync.fromResultAsync(
+      this.#http.get(
+        "/v1/manga/recommended",
+        buildParams({
+          filter: params.filter ?? "for_ios",
+          includeRankingIllusts: true,
+          includePrivacyPolicy: true,
+          offset: params.offset
+        })
+      ),
+      this.#http,
+      (page) => page.illusts
+    );
+  }
+};
+
+// src/resources/ugoira.ts
+var UgoiraResource = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Fetches ugoira metadata (ZIP URL and per-frame timings).
+   * GET /v1/ugoira/metadata
+   *
+   * @param params - Request parameters
+   */
+  metadata(params) {
+    return this.#http.get(
+      "/v1/ugoira/metadata",
+      buildParams({ illustId: params.illustId })
+    );
+  }
+};
+
+// src/resources/images.ts
+var ImageResource = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * 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) {
+    return this.#http.fetchImage(imageUrl);
+  }
+};
+
+// src/client.ts
+var PixivClient = class _PixivClient {
+  /** Illust API namespace. */
+  illusts;
+  /** Novel API namespace. */
+  novels;
+  /** User API namespace. */
+  users;
+  /** Manga API namespace. */
+  manga;
+  /** Ugoira API namespace. */
+  ugoira;
+  /** Image fetch helpers. */
+  images;
+  #auth;
+  constructor(auth, http) {
+    this.#auth = auth;
+    this.illusts = new IllustResource(http);
+    this.novels = new NovelResource(http);
+    this.users = new UserResource(http);
+    this.manga = new MangaResource(http);
+    this.ugoira = new UgoiraResource(http);
+    this.images = new ImageResource(http);
+  }
+  /**
+   * Numeric user ID of the authenticated account, as a string.
+   *
+   * Available immediately after {@link PixivClient.of} resolves.
+   */
+  get userId() {
+    return this.#auth.userId;
+  }
+  /**
+   * 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 async of(refreshToken, options) {
+    const auth = await AuthManager.login(refreshToken);
+    const http = new HttpClient(auth, options);
+    return new _PixivClient(auth, http);
+  }
+};
+
+exports.PaginatedResultAsync = PaginatedResultAsync;
+exports.PixivClient = PixivClient;
+exports.PixivFetchError = PixivFetchError;
+exports.ResultAsync = ResultAsync;
+exports.apiError = apiError;
+exports.authFailedError = authFailedError;
+exports.err = err;
+exports.failedPaginated = failedPaginated;
+exports.networkError = networkError;
+exports.ok = ok;
+exports.rateLimitError = rateLimitError;