startgg-oauth2-full 0.2.0 → 0.2.2

package/examples/discordjs/src/bot.ts

@@ -1,202 +0,0 @@
-import 'dotenv/config';
-import express from 'express';
-import { randomUUID } from 'node:crypto';
-import { Client, GatewayIntentBits, Partials, REST, Routes, SlashCommandBuilder } from 'discord.js';
-import {
-  BearerToken,
-  StartGGScope,
-  buildAuthorizeUrl,
-  createStartGGAuth2Handler,
-} from 'startgg-oauth2-full/src/auth/StartGGOAuth2';
-
-type PendingAuth = {
-  userId: string;
-  codeVerifier: string;
-  scopes: StartGGScope[];
-  timer: NodeJS.Timeout;
-};
-
-const pendingAuthorizations = new Map<string, PendingAuth>();
-const AUTH_TIMEOUT_MS = 10 * 60_000;
-
-const requiredEnv = ['DISCORD_TOKEN', 'DISCORD_CLIENT_ID', 'STARTGG_CLIENT_ID'] as const;
-const missing = requiredEnv.filter(key => !process.env[key]);
-if (missing.length) {
-  throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
-}
-
-const DISCORD_TOKEN = process.env.DISCORD_TOKEN!;
-const DISCORD_CLIENT_ID = process.env.DISCORD_CLIENT_ID!;
-const DISCORD_GUILD_ID = process.env.DISCORD_GUILD_ID;
-
-const startggConfig = {
-  clientId: process.env.STARTGG_CLIENT_ID!,
-  authEndpoint: process.env.STARTGG_AUTH_ENDPOINT ?? 'https://api.start.gg/oauth/authorize',
-  tokenEndpoint: process.env.STARTGG_TOKEN_ENDPOINT ?? 'https://api.start.gg/oauth/token',
-  redirectUri: process.env.STARTGG_REDIRECT_URI ?? 'http://localhost:5175/oauth/callback',
-};
-
-const redirectUrl = new URL(startggConfig.redirectUri);
-if (redirectUrl.protocol !== 'http:') {
-  console.warn(
-    `[discordjs example] Redirect URI ${startggConfig.redirectUri} is non-HTTP; ` +
-      'this demo only spins up an HTTP callback server. Adjust as needed.'
-  );
-}
-
-const callbackPath = redirectUrl.pathname || '/';
-const callbackPort = Number(redirectUrl.port || 5175);
-
-const startggHandler = createStartGGAuth2Handler({
-  clientId: startggConfig.clientId,
-  redirectUri: startggConfig.redirectUri,
-  authEndpoint: startggConfig.authEndpoint,
-  tokenEndpoint: startggConfig.tokenEndpoint,
-});
-
-const client = new Client({
-  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.DirectMessages],
-  partials: [Partials.Channel],
-});
-
-client.once('ready', readyClient => {
-  console.log(`[discordjs example] Logged in as ${readyClient.user.tag}`);
-});
-
-const scopes = [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL];
-
-async function registerSlashCommand(): Promise<void> {
-  const command = new SlashCommandBuilder()
-    .setName('startgg-auth')
-    .setDescription('Generate a Start.gg OAuth authorize URL with PKCE support.')
-    .setDMPermission(false);
-
-  const rest = new REST({ version: '10' }).setToken(DISCORD_TOKEN);
-  if (DISCORD_GUILD_ID) {
-    await rest.put(Routes.applicationGuildCommands(DISCORD_CLIENT_ID, DISCORD_GUILD_ID), {
-      body: [command.toJSON()],
-    });
-    console.log(
-      `[discordjs example] Registered /startgg-auth for guild ${DISCORD_GUILD_ID}. ` +
-        'Guild commands update instantly.'
-    );
-  } else {
-    await rest.put(Routes.applicationCommands(DISCORD_CLIENT_ID), {
-      body: [command.toJSON()],
-    });
-    console.log('[discordjs example] Registered /startgg-auth globally. Propagation may take up to an hour.');
-  }
-}
-
-client.on('interactionCreate', async interaction => {
-  if (!interaction.isChatInputCommand() || interaction.commandName !== 'startgg-auth') return;
-
-  await interaction.deferReply({ ephemeral: true });
-
-  const state = `${interaction.user.id}-${randomUUID()}`;
-
-  try {
-    const { url, codeVerifier } = await buildAuthorizeUrl(
-      {
-        clientId: startggConfig.clientId,
-        authEndpoint: startggConfig.authEndpoint,
-        redirectUri: startggConfig.redirectUri,
-      },
-      {
-        scopes,
-        state,
-        prompt: 'consent',
-      }
-    );
-
-    const timer = setTimeout(() => {
-      pendingAuthorizations.delete(state);
-    }, AUTH_TIMEOUT_MS);
-
-    pendingAuthorizations.set(state, {
-      userId: interaction.user.id,
-      codeVerifier,
-      scopes,
-      timer,
-    });
-
-    await interaction.editReply({
-      content: [
-        'Authorize Start.gg with PKCE:',
-        url,
-        '',
-        `This link is tied to your Discord user and expires in ${Math.round(AUTH_TIMEOUT_MS / 60000)} minutes.`,
-        'After authorizing, the bot will DM you once the callback succeeds.',
-      ].join('\n'),
-    });
-  } catch (error) {
-    console.error('[discordjs example] Failed to build authorize URL', error);
-    pendingAuthorizations.delete(state);
-    await interaction.editReply('Failed to generate authorize URL. Check the bot logs for details.');
-  }
-});
-
-const app = express();
-
-app.get(callbackPath, async (req, res) => {
-  const { state, code, error, error_description: errorDescription } = req.query as Record<string, string | undefined>;
-
-  if (error) {
-    console.warn(`[discordjs example] Authorization error: ${error} ${errorDescription ?? ''}`.trim());
-    res.status(400).send('Authorization failed. Check the bot logs for details.');
-    return;
-  }
-
-  if (!state || !code) {
-    res.status(400).send('Missing code or state.');
-    return;
-  }
-
-  const pending = pendingAuthorizations.get(state);
-  if (!pending) {
-    res.status(400).send('State no longer valid. Start a new authorization from Discord.');
-    return;
-  }
-
-  clearTimeout(pending.timer);
-  pendingAuthorizations.delete(state);
-
-  try {
-    const tokenResponse = await startggHandler.exchangeToken(code, pending.codeVerifier, pending.scopes);
-    const bearer = BearerToken.fromOAuthResponse(tokenResponse);
-    console.log('[discordjs example] OAuth success for user', pending.userId, tokenResponse);
-
-    try {
-      const user = await client.users.fetch(pending.userId);
-      const expires = bearer.expiresAt ? new Date(bearer.expiresAt).toISOString() : 'unknown';
-      await user.send(
-        [
-          '✅ Start.gg authorization complete!',
-          `Access token (truncated): ${bearer.accessToken.slice(0, 8)}…`,
-          `Expires at: ${expires}`,
-          'Check the bot logs for the full token payload and handle it securely.',
-        ].join('\n')
-      );
-    } catch (dmError) {
-      console.warn('[discordjs example] Unable to DM user with result', dmError);
-    }
-
-    res.send('Authorization complete! Return to Discord to continue.');
-  } catch (exchangeError) {
-    console.error('[discordjs example] Token exchange failed', exchangeError);
-    res.status(500).send('Token exchange failed. Check the bot logs for details.');
-  }
-});
-
-async function main(): Promise<void> {
-  await registerSlashCommand();
-  await client.login(DISCORD_TOKEN);
-  app.listen(callbackPort, () => {
-    console.log(`[discordjs example] Listening for Start.gg callbacks on http://localhost:${callbackPort}${callbackPath}`);
-  });
-}
-
-main().catch(err => {
-  console.error('[discordjs example] Fatal startup error', err);
-  process.exit(1);
-});

package/examples/discordjs/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "moduleDetection": "force",
-    "types": ["node"]
-  },
-  "include": ["src"]
-}

package/examples/nextjs/.env.example

@@ -1,7 +0,0 @@
-STARTGG_CLIENT_ID=YOUR_STARTGG_CLIENT_ID
-# STARTGG_AUTH_ENDPOINT=https://api.start.gg/oauth/authorize
-# STARTGG_TOKEN_ENDPOINT=https://api.start.gg/oauth/token
-STARTGG_REDIRECT_URI=http://localhost:3000/api/startgg/callback
-
-NEXT_PUBLIC_STARTGG_CLIENT_ID=YOUR_STARTGG_CLIENT_ID
-NEXT_PUBLIC_STARTGG_REDIRECT_URI=http://localhost:3000/api/startgg/callback

package/examples/nextjs/README.md

@@ -1,33 +0,0 @@
-# Next.js OAuth Demo
-
-This example integrates `startgg-oauth2-full` into a Next.js App Router project. It renders a page that generates a Start.gg authorize URL with PKCE, stores the verifier server-side, and exchanges the authorization code in an API route.
-
-## Setup
-```bash
-cd examples/nextjs
-cp .env.example .env.local
-# Edit the file with your Start.gg client settings
-npm install
-```
-
-Required values:
-- `STARTGG_CLIENT_ID` – Start.gg OAuth client ID (public).
-- `STARTGG_REDIRECT_URI` – defaults to `http://localhost:3000/api/startgg/callback`.
-- Optional overrides: `STARTGG_AUTH_ENDPOINT`, `STARTGG_TOKEN_ENDPOINT`.
-- `NEXT_PUBLIC_STARTGG_CLIENT_ID` mirrors the client ID for client-side display.
-- `NEXT_PUBLIC_STARTGG_REDIRECT_URI` mirrors the redirect URI for helpful UI messaging.
-
-## Development
-```bash
-npm run dev
-```
-
-Navigate to `http://localhost:3000`, click **Authorize with Start.gg**, and approve in the Start.gg window. The callback route exchanges the authorization code and displays the token payload for demo purposes.
-
-## Production Build
-```bash
-npm run build
-npm start
-```
-
-`npm run build` compiles the app, and `npm start` serves the production bundle. Adapt the in-memory PKCE store to persistent storage before deploying to serverless environments.

package/examples/nextjs/app/api/startgg/auth-url/route.ts

@@ -1,36 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { NextResponse } from 'next/server';
-import { StartGGScope, buildAuthorizeUrl } from 'startgg-oauth2-full/src/auth/StartGGOAuth2';
-import { startggConfig } from '../../../../lib/startgg';
-import { savePending } from '../../../../lib/pendingStore';
-
-export async function POST() {
-  try {
-    const state = randomUUID();
-    const scopes = [StartGGScope.USER_IDENTITY];
-
-    const { url, codeVerifier } = await buildAuthorizeUrl(startggConfig, {
-      scopes,
-      state,
-      prompt: 'consent',
-    });
-
-    savePending(state, { codeVerifier, scopes });
-
-    return NextResponse.json<AuthUrlResponse>({
-      url,
-    });
-  } catch (error) {
-    console.error('[nextjs example] Failed to generate authorize URL', error);
-    return NextResponse.json(
-      {
-        error: 'Unable to generate authorize URL. Check server logs for details.',
-      },
-      { status: 500 }
-    );
-  }
-}
-
-type AuthUrlResponse = {
-  url: string;
-};

package/examples/nextjs/app/api/startgg/callback/route.ts

@@ -1,55 +0,0 @@
-import { NextResponse } from 'next/server';
-import { BearerToken } from 'startgg-oauth2-full/src/auth/StartGGOAuth2';
-import { consumePending } from '../../../../lib/pendingStore';
-import { startggHandler } from '../../../../lib/startgg';
-
-export async function GET(request: Request) {
-  const url = new URL(request.url);
-  const state = url.searchParams.get('state');
-  const code = url.searchParams.get('code');
-  const error = url.searchParams.get('error');
-  const errorDescription = url.searchParams.get('error_description');
-
-  if (error) {
-    console.warn('[nextjs example] Authorization error from Start.gg', error, errorDescription);
-    return NextResponse.json(
-      { error, errorDescription: errorDescription ?? null },
-      { status: 400 }
-    );
-  }
-
-  if (!state || !code) {
-    return NextResponse.json(
-      { error: 'Missing state or code.' },
-      { status: 400 }
-    );
-  }
-
-  const pending = consumePending(state);
-  if (!pending) {
-    return NextResponse.json(
-      { error: 'State has expired or is invalid. Generate a new authorize URL.' },
-      { status: 400 }
-    );
-  }
-
-  try {
-    const tokenResponse = await startggHandler.exchangeToken(code, pending.codeVerifier, pending.scopes);
-    const bearer = BearerToken.fromOAuthResponse(tokenResponse);
-
-    console.log('[nextjs example] Token response', tokenResponse);
-
-    return NextResponse.json({
-      message: 'Authorization complete!',
-      scope: tokenResponse.scope ?? null,
-      expiresIn: tokenResponse.expires_in ?? null,
-      accessTokenPreview: `${bearer.accessToken.slice(0, 8)}…`,
-    });
-  } catch (err) {
-    console.error('[nextjs example] Token exchange failed', err);
-    return NextResponse.json(
-      { error: 'Token exchange failed. Inspect server logs for details.' },
-      { status: 500 }
-    );
-  }
-}

package/examples/nextjs/app/globals.css

@@ -1,48 +0,0 @@
-:root {
-  color-scheme: light dark;
-  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
-  line-height: 1.6;
-}
-
-body {
-  margin: 0;
-  padding: 2rem;
-  background: #0f172a;
-  color: #e2e8f0;
-}
-
-a {
-  color: #38bdf8;
-}
-
-button {
-  cursor: pointer;
-  border: none;
-  background: #38bdf8;
-  color: #0f172a;
-  padding: 0.75rem 1.5rem;
-  border-radius: 999px;
-  font-weight: 600;
-}
-
-button:disabled {
-  cursor: progress;
-  opacity: 0.7;
-}
-
-main {
-  max-width: 720px;
-  margin: 0 auto;
-  background: rgba(15, 23, 42, 0.6);
-  border-radius: 16px;
-  padding: 2rem;
-  box-shadow: 0 20px 50px rgba(15, 23, 42, 0.6);
-}
-
-pre {
-  padding: 1rem;
-  background: rgba(15, 23, 42, 0.9);
-  border-radius: 12px;
-  overflow-x: auto;
-  word-break: break-all;
-}

package/examples/nextjs/app/layout.tsx

@@ -1,15 +0,0 @@
-import type { Metadata } from 'next';
-import './globals.css';
-
-export const metadata: Metadata = {
-  title: 'Start.gg OAuth2 × Next.js Demo',
-  description: 'Demonstrates PKCE with startgg-oauth2-full inside a Next.js App Router project.',
-};
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}

package/examples/nextjs/app/page.tsx

@@ -1,93 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-
-type AuthResponse = {
-  url: string;
-};
-
-export default function HomePage() {
-  const [authUrl, setAuthUrl] = useState<string | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-
-  const clientId = process.env.NEXT_PUBLIC_STARTGG_CLIENT_ID ?? 'unset';
-  const redirectUri = process.env.NEXT_PUBLIC_STARTGG_REDIRECT_URI ?? 'http://localhost:3000/api/startgg/callback';
-
-  async function handleAuthorize() {
-    setLoading(true);
-    setError(null);
-    setAuthUrl(null);
-
-    try {
-      const res = await fetch('/api/startgg/auth-url', { method: 'POST' });
-      if (!res.ok) throw new Error(`Request failed (${res.status})`);
-      const data = (await res.json()) as AuthResponse;
-      setAuthUrl(data.url);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      setError(message);
-    } finally {
-      setLoading(false);
-    }
-  }
-
-  return (
-    <main>
-      <h1>Start.gg OAuth2 + Next.js</h1>
-      <p>
-        This demo calls <code>buildAuthorizeUrl</code> on the server, stores the PKCE verifier in memory, and exchanges
-        the authorization code in the callback API route. Update <code>.env.local</code> with your Start.gg client
-        values before proceeding.
-      </p>
-
-      <section>
-        <h2>Environment</h2>
-        <ul>
-          <li>
-            <strong>Client ID:</strong> <code>{clientId}</code>
-          </li>
-          <li>
-            <strong>Redirect URI:</strong> <code>{redirectUri}</code>
-          </li>
-        </ul>
-      </section>
-
-      <section>
-        <h2>Authorize</h2>
-        <p>
-          Click the button to request a Start.gg authorize URL. The link appears below so you can inspect it before
-          visiting. After finishing the Start.gg flow you&apos;ll be redirected back here and the callback will exchange
-          the code and show a success message.
-        </p>
-        <button onClick={handleAuthorize} disabled={loading}>
-          {loading ? 'Generating…' : 'Authorize with Start.gg'}
-        </button>
-        {error && (
-          <p style={{ color: '#f87171', marginTop: '1rem' }}>
-            Failed to request authorize URL: <code>{error}</code>
-          </p>
-        )}
-        {authUrl && (
-          <div style={{ marginTop: '1.5rem' }}>
-            <p>Open the link below in a new tab:</p>
-            <pre>{authUrl}</pre>
-            <p>
-              <a href={authUrl} target="_blank" rel="noreferrer">
-                Launch Start.gg OAuth
-              </a>
-            </p>
-          </div>
-        )}
-      </section>
-
-      <section>
-        <h2>Callback Output</h2>
-        <p>
-          The callback endpoint responds with a JSON summary. Keep an eye on the terminal running <code>npm run dev</code>{' '}
-          to see the raw token payload. Do not ship the in-memory verifier store or plaintext token output to production.
-        </p>
-      </section>
-    </main>
-  );
-}

package/examples/nextjs/lib/pendingStore.ts

@@ -1,37 +0,0 @@
-import type { StartGGScope } from 'startgg-oauth2-full/src/auth/StartGGOAuth2';
-
-type PendingEntry = {
-  codeVerifier: string;
-  scopes: StartGGScope[];
-  createdAt: number;
-  timeout: NodeJS.Timeout;
-};
-
-const TTL_MS = 10 * 60_000;
-const store = new Map<string, PendingEntry>();
-
-export function savePending(state: string, data: { codeVerifier: string; scopes: StartGGScope[] }) {
-  clearPending(state);
-
-  const timeout = setTimeout(() => {
-    store.delete(state);
-  }, TTL_MS);
-
-  store.set(state, { ...data, createdAt: Date.now(), timeout });
-}
-
-export function consumePending(state: string) {
-  const entry = store.get(state);
-  if (!entry) return null;
-  clearTimeout(entry.timeout);
-  store.delete(state);
-  return entry;
-}
-
-function clearPending(state: string) {
-  const current = store.get(state);
-  if (current) {
-    clearTimeout(current.timeout);
-    store.delete(state);
-  }
-}

package/examples/nextjs/lib/startgg.ts

@@ -1,28 +0,0 @@
-import { createStartGGAuth2Handler } from 'startgg-oauth2-full/src/auth/StartGGOAuth2';
-
-function readEnv(name: string, fallback?: string): string {
-  const value = process.env[name] ?? fallback;
-  if (!value) {
-    throw new Error(`[nextjs example] Missing required environment variable: ${name}`);
-  }
-  return value;
-}
-
-const clientId = readEnv('STARTGG_CLIENT_ID', process.env.NEXT_PUBLIC_STARTGG_CLIENT_ID);
-const authEndpoint = readEnv('STARTGG_AUTH_ENDPOINT', 'https://api.start.gg/oauth/authorize');
-const tokenEndpoint = readEnv('STARTGG_TOKEN_ENDPOINT', 'https://api.start.gg/oauth/token');
-const redirectUri = readEnv('STARTGG_REDIRECT_URI', 'http://localhost:3000/api/startgg/callback');
-
-export const startggConfig = {
-  clientId,
-  authEndpoint,
-  tokenEndpoint,
-  redirectUri,
-};
-
-export const startggHandler = createStartGGAuth2Handler({
-  clientId,
-  authEndpoint,
-  tokenEndpoint,
-  redirectUri,
-});

package/examples/nextjs/next-env.d.ts

@@ -1,5 +0,0 @@
-/// <reference types="next" />
-/// <reference types="next/image-types/global" />
-
-// NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.

package/examples/nextjs/next.config.mjs

@@ -1,6 +0,0 @@
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-};
-
-export default nextConfig;

package/examples/nextjs/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "startgg-oauth2-nextjs-example",
-  "version": "0.0.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint"
-  },
-  "dependencies": {
-    "next": "14.2.13",
-    "react": "18.2.0",
-    "react-dom": "18.2.0",
-    "startgg-oauth2-full": "file:../.."
-  },
-  "devDependencies": {
-    "@types/node": "^22.7.5",
-    "@types/react": "^18.2.45",
-    "@types/react-dom": "^18.2.18",
-    "eslint": "^8.57.1",
-    "eslint-config-next": "14.2.13",
-    "typescript": "^5.6.3"
-  }
-}

package/examples/nextjs/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2017",
-    "lib": ["dom", "dom.iterable", "esnext"],
-    "allowJs": true,
-    "skipLibCheck": true,
-    "strict": true,
-    "forceConsistentCasingInFileNames": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "jsx": "preserve",
-    "incremental": true,
-    "types": ["node"]
-  },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}

package/examples/node/.env.example

@@ -1,4 +0,0 @@
-STARTGG_CLIENT_ID=YOUR_STARTGG_CLIENT_ID
-# STARTGG_AUTH_URL=https://api.start.gg/oauth/authorize
-# STARTGG_TOKEN_URL=https://api.start.gg/oauth/token
-# PORT=3000

package/examples/node/README.md

@@ -1,27 +0,0 @@
-# Node CLI Demo
-
-This example demonstrates how to use the Start.gg OAuth helpers from a plain Node.js environment. It includes two scripts:
-
-- `npm run dev` — prints an authorize URL and is designed for quick, manual testing.
-- `npm run oauth-server` — hosts a callback server, opens the authorize URL in your browser, exchanges the code automatically, and logs masked tokens.
-
-## Setup
-```bash
-cd examples/node
-cp .env.example .env # optional
-npm install
-```
-
-Populate `STARTGG_CLIENT_ID` in `.env` or your shell. Override the endpoints with `STARTGG_AUTH_URL` and `STARTGG_TOKEN_URL` if you target a non-production Start.gg environment. `PORT` controls the callback server for `npm run oauth-server` (default `3000`).
-
-## Manual Flow (`npm run dev`)
-1. Run the script to generate an authorize URL.
-2. Visit the URL, approve Start.gg, and capture the `code` from the redirected address.
-3. Paste the code into the placeholder in `src/index.ts` (or extend the script to prompt for it) to exchange tokens.
-
-## Browser-Assisted Flow (`npm run oauth-server`)
-1. Run the script; it starts an HTTP listener on `http://localhost:3000/callback`.
-2. Your default browser opens to Start.gg. Complete the OAuth consent.
-3. The callback handler exchanges the code using `exchangeToken`, logs masked credentials, and exits the process.
-
-Persist tokens securely when adapting this approach to production services.