e621 3.4.1 → 3.5.1

package/README.md

@@ -37,6 +37,39 @@ const e621 = new E621({
 // e.g. use e621.posts.METHOD(), e621.users.METHOD()
 ```
 
+### Bearer Tokens & OAuth
+
+Instead of `authUser`/`authKey`, you can authenticate with a bearer token (e.g. an OAuth access token). It can be a string, or a function that returns one, which is called for every request. If both are given, the bearer token wins.
+```typescript
+const e621 = new E621({ authToken: "..." });
+```
+
+`OAuthClient` handles the OAuth 2.0 authorization code flow (with PKCE) for you, and keeps the access token refreshed. **OAuth has not been publicly released on e621 yet.**
+```typescript
+import E621, { OAuthClient } from "e621"; // or from "e621/oauth"
+
+const oauth = new OAuthClient({
+	clientId:     "",
+	clientSecret: "", // leave out for public clients
+	redirectURI:  "https://example.com/callback",
+	scopes:       ["openid", "full"],
+	token:        savedToken, // optional, restore a previous token
+	onToken:      (token) => saveToken(token), // called when the token is exchanged, refreshed, or revoked
+});
+
+// keep state & codeVerifier (e.g. in the session), and send the user to url
+const { url, state, codeVerifier } = await oauth.createAuthorizationURL();
+
+// once they're redirected back, this checks the state and exchanges the code
+await oauth.handleCallback(callbackURL, { state, codeVerifier });
+
+// getAccessToken refreshes the token when it's about to expire
+const e621 = new E621({ authToken: oauth.getAccessToken });
+
+await oauth.userInfo();
+await oauth.revoke();
+```
+
 ### Default Post Format
 
 Post-returning methods (`posts.get()`, `posts.search()`, `favorites.search()`, `popular.get()`, `iqdbQueries.get()`/`.post()`, and convenience methods on returned post models like `post.update()`) accept per-call `v2`/`mode` options and default to the legacy format when omitted. Set `defaultPostFormat` once to change that default everywhere instead of repeating the same options on every call:
@@ -52,6 +85,29 @@ await post?.update({ tags: "foo" }); // also resolves to ExtendedPost
 const legacy = await e621.posts.get(123, { v2: false });
 ```
 
+### Ratelimit Handling
+
+Every request that comes back `429 Too Many Requests` is retried automatically, waiting for the duration in the response's `Retry-After` header (or an exponential backoff starting at `ratelimit.retryDelay` seconds if that header is missing). If it's still ratelimited after `ratelimit.maxRetries` attempts, or `ratelimit.retry` is turned off, a `RatelimitError` (see `retryAfter`) is thrown instead:
+```typescript
+import { RatelimitError } from "e621";
+
+const e621 = new E621({
+	ratelimit: {
+		maxRetries: 5,     // default: 3
+		retryDelay: 2,     // default: 1 (seconds, doubled per attempt as a fallback)
+		maxRetryDelay: 30, // default: 60 (seconds, caps both the header and the fallback)
+		onRatelimit: (info) => console.warn(`ratelimited, retrying in ${info.retryAfter}s`),
+	}
+});
+
+try {
+	await e621.posts.get(123);
+} catch (err) {
+	if (err instanceof RatelimitError) console.error(`still ratelimited, retry after ${err.retryAfter}s`);
+}
+```
+Set `ratelimit: { retry: false }` to disable automatic retries and just throw `RatelimitError` on the first `429`.
+
 ## Browser Usage
 
 A pre-bundled, browser-only build (no Node built-ins) is published at `e621/browser`, for use with a plain `<script type="module">` or a CDN like jsDelivr/unpkg: