Added an OAuth flow example

Author: KartoffelChipss

.npmignore

@@ -1,6 +1,7 @@
 tests/
 testapp/
 jstestapp/
+examples/
 .idea/
 node_modules/
 .github/

.prettierignore

@@ -2,4 +2,5 @@ testapp/
 dist/
 .idea/
 node_modules/
-docs/
+docs/
+examples/

README.md

@@ -39,6 +39,7 @@ This library is a wrapper around the [Modrinth API](https://docs.modrinth.com/),
         - [Get an access token from an authorization code](#get-an-access-token-from-an-authorization-code)
     - [Miscellanous](#miscellanous)
         - [Get statistics](#get-statistics)
+- [Examples](#examples)
 - [Coverage](#coverage)
 - [License](#license)
 
@@ -323,6 +324,10 @@ const stats = await modrinth.getStatistics();
 
 [> Typedoc](https://typerinth.js.org/classes/Modrinth.html#getstatistics)
 
+## Examples
+
+- [OAuth flow example](https://github.com/KartoffelChipss/Typerinth/tree/main/examples/oauth) - A simple example on how to implement a secure OAuth 2.0 login flow using Typerinth
+
 ## Coverage
 
 You can find a list of the endpoints covered by this library in the [coverage.md](https://github.com/KartoffelChipss/Typerinth/blob/main/coverage.md) file.

examples/oauth/README.md

@@ -0,0 +1,51 @@
+# Modrinth OAuth Example with Typerinth and Express
+
+This project demonstrates how to implement a secure OAuth 2.0 login flow using [Modrinth's OAuth API](https://docs.modrinth.com/guide/oauth/) via the [`Typerinth`](https://www.npmjs.com/package/typerinth) library, Express, and express-session.
+
+---
+
+## 🚀 What This Does
+
+- Redirects users to Modrinth's authorization page
+- Validates the OAuth `state` to prevent CSRF
+- Exchanges an authorization code for an access token
+- Uses the token to retrieve the authenticated user's Modrinth account info
+
+---
+
+## 🧰 Technologies Used
+
+- [Typerinth](https://www.npmjs.com/package/typerinth)
+- [Express](https://expressjs.com/)
+- [express-session](https://www.npmjs.com/package/express-session)
+- [dotenv](https://www.npmjs.com/package/dotenv)
+- TypeScript
+
+---
+
+## 📦 Setup
+
+### 1. Install the dependencies
+
+Install the dependencies using a package manager of your choice.
+
+### 2. Configure environment variables
+
+Create a .env file:
+
+```bash
+CLIENT_ID=your-modrinth-client-id
+CLIENT_SECRET=your-modrinth-client-secret
+REDIRECT_URI=http://localhost:3000/callback
+SESSION_SECRET=super-secret-key
+```
+
+## ⚠️ Disclaimer
+
+This is a **simplified example** intended for educational and demonstration purposes. It does not include advanced features like token refresh, error recovery, persistent user sessions, or HTTPS enforcement.
+
+**Use at your own risk.**
+
+## 📄 License
+
+You can find the full license [here](https://github.com/KartoffelChipss/Typerinth/blob/main/LICENSE)

examples/oauth/server.ts

@@ -0,0 +1,94 @@
+import express from 'express';
+import session from 'express-session';
+import { Modrinth, AuthScope } from 'typerinth';
+import dotenv from 'dotenv';
+import crypto from 'crypto';
+
+dotenv.config();
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+const { CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, SESSION_SECRET } = process.env;
+
+if (!CLIENT_ID || !CLIENT_SECRET || !REDIRECT_URI || !SESSION_SECRET) {
+    throw new Error('Missing environment variables.');
+}
+
+const USER_AGENT = 'MyApp/1.0'; // Replace with your app's user agent
+
+const modrinth = new Modrinth({
+    userAgent: USER_AGENT,
+});
+
+// Session setup
+app.use(
+    session({
+        secret: SESSION_SECRET,
+        resave: false,
+        saveUninitialized: true,
+        cookie: { secure: false }, // use `cookie: { secure: true, sameSite: 'lax' }` in production behind HTTPS
+    })
+);
+
+declare module 'express-session' {
+    interface SessionData {
+        oauthState?: string;
+    }
+}
+
+// Login Route
+app.get('/login', (req, res) => {
+    const state = crypto.randomUUID(); // Generate unique state
+    req.session.oauthState = state;
+
+    const authUrl = modrinth.generateAuthorizationUrl(
+        CLIENT_ID,
+        REDIRECT_URI,
+        [AuthScope.UserRead, AuthScope.PayoutsRead],
+        state
+    );
+
+    res.redirect(authUrl);
+});
+
+// Callback Route
+app.get('/callback', async (req, res) => {
+    const code = req.query.code as string;
+    const state = req.query.state as string;
+    const storedState = req.session.oauthState;
+
+    if (!state || state !== storedState) {
+        res.status(400).send('Invalid or missing state parameter.');
+        return;
+    }
+
+    if (!code) {
+        res.status(400).send('Missing code parameter.');
+        return;
+    }
+
+    try {
+        const token = await modrinth.getToken(
+            code,
+            CLIENT_ID,
+            REDIRECT_URI,
+            CLIENT_SECRET
+        );
+
+        // Use the token to make API requests
+        const user = await modrinth.getAuthUser(token.access_token);
+        res.json({
+            message: 'Successfully authenticated with Modrinth!',
+            user,
+        });
+    } catch (error) {
+        console.error('OAuth callback error:', error);
+        res.status(500).send('Failed to authenticate.');
+    }
+});
+
+// Start server
+app.listen(PORT, () => {
+    console.log(`Server is running at http://localhost:${PORT}`);
+});