@book000/pixivts 0.57.0 → 0.58.0

package/dist/index.d.cts

@@ -446,12 +446,71 @@ declare class PaginatedResultAsync<TPage extends PagedResponse, TItem> extends R
  */
 declare function failedPaginated<TPage extends PagedResponse, TItem>(error: PixivError, http: HttpClient, getItems: (page: TPage) => TItem[]): PaginatedResultAsync<TPage, TItem>;
 
+/**
+ * Typed cursor parameters extracted from a pixiv `next_url`.
+ *
+ * Different endpoints use different cursor fields; only the fields present
+ * in the URL will be defined.
+ *
+ * | Field | Endpoint(s) |
+ * |---|---|
+ * | `maxBookmarkId` | `GET /v1/user/bookmarks/illust` |
+ * | `maxBookmarkIdForRecommend` | `GET /v1/illust/recommended`, `GET /v1/novel/recommended` |
+ * | `minBookmarkIdForRecentIllust` | `GET /v1/illust/recommended` |
+ * | `offset` | search, ranking, recommended, user lists, … |
+ * | `lastOrder` | `GET /v2/novel/series` |
+ */
+interface ParsedNextUrl {
+    /** Cursor for `GET /v1/user/bookmarks/illust`. */
+    maxBookmarkId?: number;
+    /** Cursor for `GET /v1/illust/recommended` and `GET /v1/novel/recommended`. */
+    maxBookmarkIdForRecommend?: number;
+    /** Secondary cursor for `GET /v1/illust/recommended`. */
+    minBookmarkIdForRecentIllust?: number;
+    /** Zero-based offset for general list endpoints. */
+    offset?: number;
+    /** Cursor for `GET /v2/novel/series`. */
+    lastOrder?: number;
+}
+/**
+ * Parses a pixiv `next_url` into a typed cursor object.
+ *
+ * Pass the `next_url` field from any paginated response to extract the
+ * cursor parameters needed to resume pagination from a saved position.
+ *
+ * @example
+ * ```ts
+ * const page = await client.users.bookmarks.illusts({ userId: client.userId })
+ * if (page.isOk && page.value.next_url) {
+ *   const cursor = parseNextUrl(page.value.next_url)
+ *   // Resume later:
+ *   const next = await client.users.bookmarks.illusts({
+ *     userId: client.userId,
+ *     maxBookmarkId: cursor.maxBookmarkId,
+ *   })
+ * }
+ * ```
+ *
+ * @param url - The `next_url` string returned by a pixiv list endpoint
+ * @returns Typed cursor parameters; fields absent in the URL are `undefined`
+ */
+declare function parseNextUrl(url: string): ParsedNextUrl;
+
 /**
  * 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.
+ * Each option is exported as both a runtime `const` object (for enum-like
+ * access, e.g. `BookmarkRestrict.PUBLIC`) and a TypeScript `type` (so plain
+ * string literals such as `'public'` are also accepted).
+ *
+ * @example
+ * ```ts
+ * // Enum-like usage
+ * await client.illusts.bookmarkAdd({ illustId: 123, restrict: BookmarkRestrict.PUBLIC })
+ *
+ * // Plain string literal — also valid
+ * await client.illusts.bookmarkAdd({ illustId: 123, restrict: 'public' })
+ * ```
  */
 /**
  * Search match target for illust / novel searches.
@@ -461,7 +520,13 @@ declare function failedPaginated<TPage extends PagedResponse, TItem>(error: Pixi
  * - `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';
+declare const SearchTarget: {
+    readonly PARTIAL_MATCH_FOR_TAGS: "partial_match_for_tags";
+    readonly EXACT_MATCH_FOR_TAGS: "exact_match_for_tags";
+    readonly TITLE_AND_CAPTION: "title_and_caption";
+    readonly KEYWORD: "keyword";
+};
+type SearchTarget = (typeof SearchTarget)[keyof typeof SearchTarget];
 /**
  * Sort order for search results.
  *
@@ -469,7 +534,12 @@ type SearchTarget = 'partial_match_for_tags' | 'exact_match_for_tags' | 'title_a
  * - `date_asc` — oldest first
  * - `popular_desc` — most bookmarks first (premium only)
  */
-type SearchSort = 'date_desc' | 'date_asc' | 'popular_desc';
+declare const SearchSort: {
+    readonly DATE_DESC: "date_desc";
+    readonly DATE_ASC: "date_asc";
+    readonly POPULAR_DESC: "popular_desc";
+};
+type SearchSort = (typeof SearchSort)[keyof typeof SearchSort];
 /**
  * Date range filter for search results.
  *
@@ -477,47 +547,93 @@ type SearchSort = 'date_desc' | 'date_asc' | 'popular_desc';
  * - `within_last_week` — past 7 days
  * - `within_last_month` — past 30 days
  */
-type SearchDuration = 'within_last_day' | 'within_last_week' | 'within_last_month';
+declare const SearchDuration: {
+    readonly WITHIN_LAST_DAY: "within_last_day";
+    readonly WITHIN_LAST_WEEK: "within_last_week";
+    readonly WITHIN_LAST_MONTH: "within_last_month";
+};
+type SearchDuration = (typeof SearchDuration)[keyof typeof SearchDuration];
 /**
  * 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';
+declare const RankingMode: {
+    readonly DAY: "day";
+    readonly DAY_MALE: "day_male";
+    readonly DAY_FEMALE: "day_female";
+    readonly WEEK_ORIGINAL: "week_original";
+    readonly WEEK_ROOKIE: "week_rookie";
+    readonly WEEK: "week";
+    readonly MONTH: "month";
+    readonly DAY_AI: "day_ai";
+    readonly DAY_R18: "day_r18";
+    readonly WEEK_R18: "week_r18";
+    readonly DAY_MALE_R18: "day_male_r18";
+    readonly DAY_FEMALE_R18: "day_female_r18";
+    readonly DAY_R18_AI: "day_r18_ai";
+};
+type RankingMode = (typeof RankingMode)[keyof typeof RankingMode];
 /**
  * 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';
+declare const NovelRankingMode: {
+    readonly DAY: "day";
+    readonly WEEK: "week";
+    readonly DAY_MALE: "day_male";
+    readonly DAY_FEMALE: "day_female";
+    readonly WEEK_ROOKIE: "week_rookie";
+    readonly DAY_R18: "day_r18";
+    readonly WEEK_R18: "week_r18";
+    readonly DAY_R18_AI: "day_r18_ai";
+};
+type NovelRankingMode = (typeof NovelRankingMode)[keyof typeof NovelRankingMode];
 /**
  * Visibility restriction for bookmarks.
  *
  * - `public` — publicly visible (default)
  * - `private` — visible only to the owner
  */
-type BookmarkRestrict = 'public' | 'private';
+declare const BookmarkRestrict: {
+    readonly PUBLIC: "public";
+    readonly PRIVATE: "private";
+};
+type BookmarkRestrict = (typeof BookmarkRestrict)[keyof typeof BookmarkRestrict];
 /**
  * Visibility restriction for follows.
  *
  * - `public` — publicly visible (default)
  * - `private` — visible only to the owner
  */
-type FollowRestrict = 'public' | 'private';
+declare const FollowRestrict: {
+    readonly PUBLIC: "public";
+    readonly PRIVATE: "private";
+};
+type FollowRestrict = (typeof FollowRestrict)[keyof typeof FollowRestrict];
 /**
  * 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';
+declare const OSFilter: {
+    readonly FOR_IOS: "for_ios";
+    readonly FOR_ANDROID: "for_android";
+};
+type OSFilter = (typeof OSFilter)[keyof typeof OSFilter];
 /**
  * Work type filter for user illust listings.
  *
  * - `illust` — illustrations only
  * - `manga` — manga only
  */
-type UserIllustType = 'illust' | 'manga';
+declare const UserIllustType: {
+    readonly ILLUST: "illust";
+    readonly MANGA: "manga";
+};
+type UserIllustType = (typeof UserIllustType)[keyof typeof UserIllustType];
 
 /**
  * Public types for @book000/pixivts.
@@ -1155,6 +1271,16 @@ interface IllustRecommendedParams {
     filter?: OSFilter;
     /** Zero-based offset for pagination. */
     offset?: number;
+    /**
+     * Cursor for resuming pagination: the `maxBookmarkIdForRecommend` value
+     * extracted from a previous page's `next_url` via {@link parseNextUrl}.
+     */
+    maxBookmarkIdForRecommend?: number;
+    /**
+     * Secondary cursor for resuming pagination: the `minBookmarkIdForRecentIllust`
+     * value extracted from a previous page's `next_url` via {@link parseNextUrl}.
+     */
+    minBookmarkIdForRecentIllust?: number;
 }
 /** Parameters for fetching an illust series. */
 interface IllustSeriesParams {
@@ -1186,6 +1312,16 @@ declare class IllustResource {
      * GET /v1/illust/detail
      *
      * @param params - Request parameters
+     *
+     * @example
+     * ```ts
+     * const result = await client.illusts.detail({ illustId: 12345 })
+     * if (result.isOk) {
+     *   console.log(result.value.illust.title)
+     * } else {
+     *   console.error(result.error)
+     * }
+     * ```
      */
     detail(params: IllustDetailParams): ResultAsync<IllustDetailResponse, PixivError>;
     /**
@@ -1200,6 +1336,20 @@ declare class IllustResource {
      * GET /v1/search/illust
      *
      * @param params - Request parameters
+     *
+     * @example
+     * ```ts
+     * // Iterate all results across pages
+     * for await (const illust of client.illusts.search({ word: 'cat' }).items()) {
+     *   console.log(illust.title)
+     * }
+     *
+     * // Fetch only the first page
+     * const page = await client.illusts.search({ word: 'cat' })
+     * if (page.isOk) {
+     *   console.log(page.value.illusts.length)
+     * }
+     * ```
      */
     search(params: IllustSearchParams): PaginatedResultAsync<IllustListPage, IllustListPage['illusts'][number]>;
     /**
@@ -1296,6 +1446,11 @@ interface NovelRecommendedParams {
     filter?: OSFilter;
     /** Zero-based offset for pagination. */
     offset?: number;
+    /**
+     * Cursor for resuming pagination: the `maxBookmarkIdForRecommend` value
+     * extracted from a previous page's `next_url` via {@link parseNextUrl}.
+     */
+    maxBookmarkIdForRecommend?: number;
 }
 /** Parameters for fetching a novel series. */
 interface NovelSeriesParams {
@@ -1327,6 +1482,16 @@ declare class NovelResource {
      * GET /v2/novel/detail
      *
      * @param params - Request parameters
+     *
+     * @example
+     * ```ts
+     * const result = await client.novels.detail({ novelId: 67890 })
+     * if (result.isOk) {
+     *   console.log(result.value.novel.title)
+     * } else {
+     *   console.error(result.error)
+     * }
+     * ```
      */
     detail(params: NovelDetailParams): ResultAsync<NovelDetailResponse, PixivError>;
     /**
@@ -1351,6 +1516,20 @@ declare class NovelResource {
      * GET /v1/search/novel
      *
      * @param params - Request parameters
+     *
+     * @example
+     * ```ts
+     * // Iterate all results across pages
+     * for await (const novel of client.novels.search({ word: 'fantasy' }).items()) {
+     *   console.log(novel.title)
+     * }
+     *
+     * // Fetch only the first page
+     * const page = await client.novels.search({ word: 'fantasy' })
+     * if (page.isOk) {
+     *   console.log(page.value.novels.length)
+     * }
+     * ```
      */
     search(params: NovelSearchParams): PaginatedResultAsync<NovelListPage, PixivNovelItem>;
     /**
@@ -1481,6 +1660,25 @@ declare class UserBookmarksResource {
      * GET /v1/user/bookmarks/illust
      *
      * @param params - Request parameters
+     *
+     * @example
+     * ```ts
+     * // Iterate all bookmarked illusts across pages
+     * for await (const illust of client.users.bookmarks.illusts({ userId: client.userId }).items()) {
+     *   console.log(illust.title)
+     * }
+     *
+     * // Resume from a saved cursor
+     * import { parseNextUrl } from '@book000/pixivts'
+     * const page = await client.users.bookmarks.illusts({ userId: client.userId })
+     * if (page.isOk && page.value.next_url) {
+     *   const cursor = parseNextUrl(page.value.next_url)
+     *   const next = await client.users.bookmarks.illusts({
+     *     userId: client.userId,
+     *     maxBookmarkId: cursor.maxBookmarkId,
+     *   })
+     * }
+     * ```
      */
     illusts(params: UserBookmarksIllustParams): PaginatedResultAsync<UserBookmarksIllustPage, PixivIllustItem>;
     /**
@@ -1488,6 +1686,14 @@ declare class UserBookmarksResource {
      * GET /v1/user/bookmarks/novel
      *
      * @param params - Request parameters
+     *
+     * @example
+     * ```ts
+     * // Iterate all bookmarked novels across pages
+     * for await (const novel of client.users.bookmarks.novels({ userId: client.userId }).items()) {
+     *   console.log(novel.title)
+     * }
+     * ```
      */
     novels(params: UserBookmarksNovelParams): PaginatedResultAsync<UserBookmarksNovelPage, PixivNovelItem>;
 }
@@ -1646,11 +1852,20 @@ declare class PixivClient {
     readonly images: ImageResource;
     private constructor();
     /**
-     * Numeric user ID of the authenticated account, as a string.
+     * Numeric user ID of the authenticated account.
      *
      * Available immediately after {@link PixivClient.of} resolves.
+     * The pixiv OAuth endpoint returns the ID as a string; this getter
+     * normalises it to `number` for consistency with resource method params
+     * (e.g. `UserBookmarksIllustParams.userId`).
+     *
+     * @example
+     * ```ts
+     * const client = await PixivClient.of(refreshToken)
+     * const bookmarks = await client.users.bookmarks.illusts({ userId: client.userId })
+     * ```
      */
-    get userId(): string;
+    get userId(): number;
     /**
      * Creates a PixivClient by refreshing the given token.
      *
@@ -1661,4 +1876,4 @@ declare class 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 };
+export { BookmarkRestrict, type ErrResult, 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, NovelRankingMode, type NovelRankingParams, type NovelRecommendedPage, type NovelRecommendedParams, type NovelRelatedParams, type NovelSearchParams, type NovelSeriesDetail, type NovelSeriesPage, type NovelSeriesParams, type NovelTextParams, OSFilter, type OkResult, type PagedResponse, PaginatedResultAsync, type ParsedNextUrl, 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, RankingMode, type ResponseInterceptor, type ResponseRecord, type Result, ResultAsync, SearchDuration, SearchSort, 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, UserIllustType, type UserIllustsPage, type UserIllustsParams, type UserNovelsPage, type UserNovelsParams, type ZipUrls, apiError, authFailedError, err, failedPaginated, networkError, ok, parseNextUrl, rateLimitError };