e621 3.5.0 → 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:

package/dist/browser/e621.js

@@ -37,10 +37,12 @@ ${error.message}`;
         if ("message" in error && typeof error.message === "string")
           message += `
 ${error.message}`;
-        else if ("error" in error && typeof error.error === "string")
+        else if ("error" in error && typeof error.error === "string") {
           message += `
 ${error.error}`;
-        else if ("errors" in error && typeof error.errors === "object" && error.errors !== null) {
+          if ("error_description" in error && typeof error.error_description === "string")
+            message += `: ${error.error_description}`;
+        } else if ("errors" in error && typeof error.errors === "object" && error.errors !== null) {
           for (const [key, value] of Object.entries(error.errors)) {
             if (typeof value === "string")
               message += `
@@ -71,6 +73,19 @@ var RatelimitError = class extends UnexpectedResponseError {
 Retry after ${this.retryAfter}s`);
   }
 };
+var OAuthCallbackError = class extends Error {
+  /** The OAuth error code, e.g. `access_denied`. */
+  error;
+  errorDescription;
+  name = "OAuthCallbackError";
+  state;
+  constructor(error, errorDescription, state) {
+    super(errorDescription ? `${error}: ${errorDescription}` : error);
+    this.error = error;
+    this.errorDescription = errorDescription;
+    this.state = state;
+  }
+};
 
 // dist/lib/generated/core/serverSentEvents.js
 function createSseClient({ onRequest, onSseError, onSseEvent, responseTransformer, responseValidator, sseDefaultRetryDelay, sseMaxRetryAttempts, sseMaxRetryDelay, sseSleepFn, url, ...options }) {
@@ -851,12 +866,13 @@ var createClient = (config = {}) => {
 };
 
 // dist/lib/version.js
-var VERSION = "3.5.0";
+var VERSION = "3.5.1";
 
 // dist/lib/client.js
 function createE621Client(options) {
   const resolved = {
     authKey: options?.authKey ?? null,
+    authToken: options?.authToken ?? null,
     authUser: options?.authUser ?? null,
     baseURL: options?.baseURL ?? "https://e621.net",
     ratelimit: {
@@ -871,8 +887,17 @@ function createE621Client(options) {
     userAgent: options?.userAgent ?? `E621/${VERSION} (https://github.com/DonovanDMC/E621${options?.authUser ? `; "${options.authUser}"` : ""})`,
     userAgentInQuery: options?.userAgentInQuery ?? "window" in globalThis
   };
-  let config;
-  const commonConfig = {
+  const getAuthorization = async () => {
+    if (resolved.authToken) {
+      const token = typeof resolved.authToken === "function" ? await resolved.authToken() : resolved.authToken;
+      if (token)
+        return `Bearer ${token}`;
+    }
+    if (resolved.authKey && resolved.authUser)
+      return `Basic ${btoa(`${resolved.authUser}:${resolved.authKey}`)}`;
+    return null;
+  };
+  const config = createConfig({
     baseUrl: resolved.baseURL,
     headers: resolved.userAgentInQuery ? void 0 : {
       "User-Agent": resolved.userAgent
@@ -882,19 +907,21 @@ function createE621Client(options) {
       if (input instanceof Request) {
         url = input.url;
         method = input.method.toLowerCase();
-        if (!input.headers.has("Authorization") && resolved.authKey && resolved.authUser) {
-          input.headers.set("Authorization", `Basic ${btoa(`${resolved.authUser}:${resolved.authKey}`)}`);
+        if (!input.headers.has("Authorization")) {
+          const authorization = await getAuthorization();
+          if (authorization)
+            input.headers.set("Authorization", authorization);
         }
       } else if (init) {
         url = input.toString();
         method = init.method?.toLowerCase() ?? "get";
-        if (resolved.authKey && resolved.authUser) {
-          const headers = new Headers(init.headers);
-          if (!headers.has("Authorization")) {
-            headers.set("Authorization", `Basic ${btoa(`${resolved.authUser}:${resolved.authKey}`)}`);
-          }
-          init.headers = headers;
+        const headers = new Headers(init.headers);
+        if (!headers.has("Authorization")) {
+          const authorization = await getAuthorization();
+          if (authorization)
+            headers.set("Authorization", authorization);
         }
+        init.headers = headers;
       }
       if (resolved.userAgentInQuery && input instanceof Request) {
         const requestURL = new URL(input.url);
@@ -930,20 +957,7 @@ function createE621Client(options) {
       }
       return res;
     }
-  };
-  if (resolved.authKey && resolved.authUser) {
-    config = createConfig({
-      ...commonConfig,
-      auth: (auth) => {
-        if (auth.scheme === "basic") {
-          return `${resolved.authUser}:${resolved.authKey}`;
-        }
-        return;
-      }
-    });
-  } else {
-    config = createConfig(commonConfig);
-  }
+  });
   return { client: createClient(config), options: resolved };
 }
 
@@ -22440,6 +22454,200 @@ var OAuthErrorSchema = {
   }
 };
 
+// dist/lib/OAuthClient.js
+function base64URL(bytes) {
+  let str = "";
+  for (const byte of bytes)
+    str += String.fromCharCode(byte);
+  return btoa(str).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function randomString(byteLength = 32) {
+  return base64URL(crypto.getRandomValues(new Uint8Array(byteLength)));
+}
+var OAuthClient = class _OAuthClient {
+  _clientSecret;
+  _discovery;
+  _onToken;
+  _refreshing;
+  _token;
+  _tokenInfo;
+  _tokens;
+  _userinfo;
+  baseURL;
+  clientId;
+  redirectURI;
+  refreshLeeway;
+  scopes;
+  constructor(options) {
+    const { clientId, clientSecret, onToken, redirectURI, refreshLeeway, scopes, token, ...clientOptions } = options;
+    this.clientId = clientId;
+    this.redirectURI = redirectURI ?? null;
+    this.refreshLeeway = refreshLeeway ?? 60;
+    this.scopes = scopes ?? [];
+    const { client: client2, options: resolved } = createE621Client(clientOptions);
+    const { client: authedClient } = createE621Client({ ...clientOptions, authToken: () => this.getAccessToken() });
+    this.baseURL = resolved.baseURL;
+    Object.defineProperties(this, {
+      _clientSecret: { value: clientSecret ?? null, enumerable: false },
+      _discovery: { value: new DoorkeeperOpenidConnectDiscovery(void 0, client2), enumerable: false },
+      _onToken: { value: onToken, enumerable: false },
+      _refreshing: { value: null, writable: true, enumerable: false },
+      _token: { value: token ?? null, writable: true, enumerable: false },
+      _tokenInfo: { value: new DoorkeeperTokenInfo(void 0, authedClient), enumerable: false },
+      _tokens: { value: new DoorkeeperTokens(void 0, client2), enumerable: false },
+      _userinfo: { value: new DoorkeeperOpenidConnectUserinfo(void 0, authedClient), enumerable: false }
+    });
+    this.getAccessToken = this.getAccessToken.bind(this);
+  }
+  /** Creates a PKCE `code_challenge` (S256) from a code verifier. */
+  static async createCodeChallenge(codeVerifier) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier));
+    return base64URL(new Uint8Array(digest));
+  }
+  /** Creates a random PKCE code verifier. */
+  static createCodeVerifier() {
+    return randomString(32);
+  }
+  /** Creates a random state value. */
+  static createState() {
+    return randomString(16);
+  }
+  /** When the current access token expires, as a unix timestamp in milliseconds - `null` if there's no token. */
+  get expiresAt() {
+    if (this._token === null)
+      return null;
+    return (this._token.created_at + this._token.expires_in) * 1e3;
+  }
+  /** Whether the current access token is expired (or within {@link OAuthClientOptions.refreshLeeway} of expiring). */
+  get isExpired() {
+    const expiresAt = this.expiresAt;
+    return expiresAt === null || Date.now() >= expiresAt - this.refreshLeeway * 1e3;
+  }
+  /** The current token, if any. */
+  get token() {
+    return this._token;
+  }
+  _clientAuth() {
+    return this._clientSecret === null ? { client_id: this.clientId } : { client_id: this.clientId, client_secret: this._clientSecret };
+  }
+  _requireToken() {
+    if (this._token === null)
+      throw new Error("No OAuth token is available, the user must authorize first.");
+    return this._token;
+  }
+  /** Builds the url to send the user to, to authorize your application. */
+  async createAuthorizationURL(options = {}) {
+    const codeVerifier = options.codeVerifier ?? _OAuthClient.createCodeVerifier();
+    const state = options.state ?? _OAuthClient.createState();
+    const redirectURI = options.redirectURI ?? this.redirectURI;
+    const scopes = options.scopes ?? this.scopes;
+    const url = new URL("/oauth/authorize", this.baseURL);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", this.clientId);
+    if (redirectURI)
+      url.searchParams.set("redirect_uri", redirectURI);
+    if (scopes.length !== 0)
+      url.searchParams.set("scope", scopes.join(" "));
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", await _OAuthClient.createCodeChallenge(codeVerifier));
+    url.searchParams.set("code_challenge_method", "S256");
+    if (options.nonce)
+      url.searchParams.set("nonce", options.nonce);
+    if (options.prompt)
+      url.searchParams.set("prompt", options.prompt);
+    return { codeVerifier, redirectURI, state, url: url.toString() };
+  }
+  /** Gets e621's OpenID Connect discovery document. */
+  async discovery() {
+    return this._discovery.provider();
+  }
+  /** Exchanges an authorization code for a token, and stores it. */
+  async exchangeCode(code, codeVerifier, redirectURI = this.redirectURI) {
+    const token = await this._tokens.create({
+      grant_type: "authorization_code",
+      code,
+      code_verifier: codeVerifier,
+      redirect_uri: redirectURI ?? void 0,
+      ...this._clientAuth()
+    });
+    await this.setToken(token);
+    return token;
+  }
+  /**
+   * Gets a valid access token, refreshing it first if it's expired. Already bound, so it can be passed
+   * directly as {@link Options.authToken}.
+   */
+  async getAccessToken() {
+    if (this._token === null)
+      throw new Error("No OAuth token is available, the user must authorize first.");
+    if (this.isExpired)
+      return (await this.refresh()).access_token;
+    return this._token.access_token;
+  }
+  /**
+   * Validates the url the user was redirected back to (state, and any error e621 sent), then exchanges
+   * its code for a token.
+   * @param callbackURL - The full callback url, or just its query string.
+   */
+  async handleCallback(callbackURL, options) {
+    const params = callbackURL instanceof URLSearchParams ? callbackURL : typeof callbackURL === "string" && !/^[a-z][\d+.a-z-]*:/i.test(callbackURL) ? new URLSearchParams(callbackURL) : new URL(callbackURL).searchParams;
+    const state = params.get("state");
+    const error = params.get("error");
+    if (error)
+      throw new OAuthCallbackError(error, params.get("error_description"), state);
+    if (state !== options.state)
+      throw new OAuthCallbackError("invalid_state", "The callback's state does not match the expected state.", state);
+    const code = params.get("code");
+    if (!code)
+      throw new OAuthCallbackError("invalid_request", "The callback is missing the authorization code.", state);
+    return this.exchangeCode(code, options.codeVerifier, options.redirectURI ?? this.redirectURI);
+  }
+  /** Introspects a token - by default the current access token. */
+  async introspect(token = this._requireToken().access_token) {
+    return this._tokens.introspect({ token, ...this._clientAuth() });
+  }
+  /**
+   * Refreshes the access token, and stores the new token. Concurrent calls share the same request.
+   * @param scopes - Narrow the new token to these scopes.
+   */
+  async refresh(scopes) {
+    if (this._refreshing)
+      return this._refreshing;
+    const refreshToken = this._requireToken().refresh_token;
+    this._refreshing = this._tokens.create({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      scope: scopes?.join(" "),
+      ...this._clientAuth()
+    }).then(async (token) => {
+      await this.setToken(token);
+      return token;
+    }).finally(() => {
+      this._refreshing = null;
+    });
+    return this._refreshing;
+  }
+  /** Revokes the current token (which also invalidates its refresh token), and clears it. */
+  async revoke() {
+    const token = this._requireToken();
+    await this._tokens.revoke({ token: token.access_token, token_type_hint: "access_token", ...this._clientAuth() });
+    await this.setToken(null);
+  }
+  /** Replaces the stored token, calling {@link OAuthClientOptions.onToken}. */
+  async setToken(token) {
+    this._token = token;
+    await this._onToken?.(token);
+  }
+  /** Gets metadata about the current access token. */
+  async tokenInfo() {
+    return this._tokenInfo.get();
+  }
+  /** Gets the OpenID Connect claims of the authorized user, gated by the token's scopes. */
+  async userInfo() {
+    return this._userinfo.get();
+  }
+};
+
 // dist/lib/index.js
 var E621 = class {
   client;
@@ -22488,6 +22696,8 @@ export {
   NewsUpdate_default as NewsUpdate,
   Note_default as Note,
   NoteVersion_default as NoteVersion,
+  OAuthCallbackError,
+  OAuthClient,
   Pool_default as Pool,
   PoolVersion_default as PoolVersion,
   Post_default as Post,