@book000/pixivts 0.55.0 → 0.56.0

package/README.md

@@ -1,35 +1,131 @@
-# pixivts
+# @book000/pixivts
 
-[pixiv](https://www.pixiv.net/) Unofficial API Library for TypeScript
+[pixiv](https://www.pixiv.net/) Unofficial API Library for TypeScript.
 
-This is NOT a fork of [@ibaraki-douji/pixivts](https://www.npmjs.com/package/@ibaraki-douji/pixivts). However, I do use it as a reference.
+## Installation
 
-## 🚀 Install
+```shell
+npm install @book000/pixivts
+# or
+pnpm add @book000/pixivts
+# or
+yarn add @book000/pixivts
+```
 
-This library is available at npm: [@book000/pixivts](https://www.npmjs.com/package/@book000/pixivts)
+## Features
 
-If you are using npm:
+- **Zero runtime dependencies** — no axios, no zod at runtime; uses native `fetch`
+- **Result-typed API** — every method returns `Result<T, PixivError>` (no thrown exceptions)
+- **ESM + CJS dual output** — works in Node.js (ESM/CJS) and edge runtimes
+- **Paginated results** — `PaginatedResultAsync` with async generator for multi-page iteration
+- **Resource-based API** — `illusts`, `novels`, `users`, `manga`, `ugoira`, `images` namespaces
+- **Token refresh** — automatic refresh-token → access-token exchange on startup and 401 retry
 
-```shell
-npm install @book000/pixivts
+## Quick Start
+
+```typescript
+import { PixivClient } from '@book000/pixivts'
+
+const client = await PixivClient.of(process.env.PIXIV_REFRESH_TOKEN!)
+
+// Fetch a single illust
+const result = await client.illusts.detail({ illustId: 12345 })
+if (result.isOk) {
+  console.log(result.value.illust.title)
+}
+
+// Search illusts (single page)
+const searchResult = await client.illusts.search({ word: 'hatsune miku' })
+if (searchResult.isOk) {
+  for (const illust of searchResult.value.illusts) {
+    console.log(illust.id, illust.title)
+  }
+}
+
+// Iterate over all pages
+for await (const page of client.illusts.search({ word: 'hatsune miku' }).pages()) {
+  for (const illust of page.illusts) {
+    console.log(illust.id, illust.title)
+  }
+}
+
+// Iterate over all items across pages (async generator — throws on fetch error)
+for await (const illust of client.illusts.search({ word: 'hatsune miku' }).items()) {
+  console.log(illust.id, illust.title)
+}
 ```
 
-or if you are using yarn:
+## API
 
-```shell
-yarn add @book000/pixivts
+### `PixivClient.of(refreshToken, opts?)`
+
+Creates a `PixivClient` by exchanging the given refresh token for an access token.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `refreshToken` | `string` | — | pixiv OAuth refresh token |
+| `opts.retry.maxRetries` | `number` | `3` | Max 429 retry attempts |
+| `opts.retry.waitMs` | `number` | `10000` | Default wait (ms) when no `Retry-After` header is present |
+| `opts.onResponse` | `ResponseInterceptor` | — | Called after every API response (used by `@book000/pixivts-db-mysql`) |
+
+### Resources
+
+| Namespace | Methods |
+|---|---|
+| `illusts` | `detail`, `related`, `search`, `ranking`, `recommended`, `series`, `bookmarkAdd`, `bookmarkDelete` |
+| `novels` | `detail`, `text`, `related`, `search`, `ranking`, `recommended`, `series`, `bookmarkAdd`, `bookmarkDelete` |
+| `users` | `detail`, `illusts`, `novels`, `following`, `followAdd`, `followDelete` |
+| `users.bookmarks` | `illusts`, `novels` |
+| `manga` | `recommended` |
+| `ugoira` | `metadata` |
+| `images` | `fetch` |
+
+### Error Handling
+
+```typescript
+import type { PixivError } from '@book000/pixivts'
+
+const result = await client.illusts.detail({ illustId: 12345 })
+
+if (result.isErr) {
+  const err: PixivError = result.error
+  switch (err.type) {
+    case 'rate_limit':
+      console.error(`Rate limited. Retry after ${err.retryAfter}ms`)
+      break
+    case 'auth_failed':
+      console.error(`Auth failed with status ${err.status}`)
+      break
+    case 'api_error':
+      console.error(`API error ${err.status}`)
+      break
+    case 'network':
+      console.error('Network error', err.cause)
+      break
+  }
+}
 ```
 
-## ✨ Features
+### Result API
 
-- It mainly uses the private API that the iOS pixiv app communicates with. Inspired by [pixivpy](https://github.com/upbit/pixivpy).
-- All API request methods return an [axios](https://www.npmjs.com/package/axios) response.
-  This allows this library users to use all responses, without having to wait for library updates if the API response changes.
+```typescript
+// Transform on success
+const title = result.map((data) => data.illust.title)
+
+// Provide a fallback on error
+const titleOrFallback = result.unwrapOr('Unknown')
+
+// Match both branches
+const message = result.match(
+  (data) => `Title: ${data.illust.title}`,
+  (err) => `Error: ${err.type}`,
+)
+```
 
-## 📚 API Document
+## API Documentation
 
-The API documentation for this library is hosted on GitHub Pages and can be found [here](https://book000.github.io/pixivts/).
+Full API reference: <https://book000.github.io/pixivts/>
 
-## 📑 License
+## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](../../LICENSE)