startgg-oauth2-full 0.1.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,18 @@
+---
+name: Bug report
+about: Report a bug
+---
+
+**Describe the bug**
+…
+
+**Repro**
+1. …
+2. …
+
+**Expected**
+…
+
+**Env**
+- Node:
+- Browser:

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Suggest an idea
+---
+
+**Problem**
+…
+
+**Proposal**
+…
+
+**Alternatives**
+…

package/.github/pull_request_template.md

@@ -0,0 +1,30 @@
+# Pull Request
+
+## Summary
+Explain the change concisely. What does this PR do and why?
+
+## Type
+- [ ] feat (new feature)
+- [ ] fix (bug fix)
+- [ ] refactor (no functional change)
+- [ ] docs (docs only)
+- [ ] test (tests only)
+- [ ] chore (infrastructure/CI/build)
+
+## Checklist
+- [ ] I ran `npm run build` successfully.
+- [ ] I ran `npm test` successfully and added/updated tests where behavior changed.
+- [ ] I updated README/docs if public API or flows changed.
+- [ ] I did not commit secrets/tokens and scrubbed logs.
+
+## Breaking Changes
+- [ ] Yes — describe impact and migration steps below
+- [ ] No
+
+If **Yes**, detail migration notes:
+
+## Screenshots / Demos (if applicable)
+Paste or link minimal repro or demo outputs.
+
+## Related Issues
+Link to issues (e.g., #123).

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm test -- --ci

package/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to startgg-oauth2-full
+
+## Prerequisites
+- Node 18+ and npm 9+
+- Git
+
+## Layout
+- `src` — library (TypeScript)
+- `__tests__` — unit tests
+- `examples` — browser + node demos (includes local redirect catcher)
+- `.github/workflows/ci.yml` — CI (build + tests)
+
+## Setup
+```bash
+npm i
+npm run build
+npm test
+```
+
+## Run examples
+```bash
+npm run dev:browser
+npm run dev:node
+STARTGG_CLIENT_ID=your_id \
+STARTGG_AUTH_URL=https://api.start.gg/oauth/authorize \
+STARTGG_TOKEN_URL=https://api.start.gg/oauth/token \
+npm run dev:node:server
+```
+
+## Branch & PR
+- Branch naming: `feat/*`, `fix/*`, `docs/*`, `chore/*`
+- Before PR:
+  - [ ] `npm run build` passes
+  - [ ] `npm test` passes
+  - [ ] Tests added/updated when changing behavior
+  - [ ] README/docs updated if API or flows changed

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+<!-- Badges -->
+
+<p align="left">
+  <a href="https://github.com/0xabadbabe-ops/startgg-oauth2-full/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/0xabadbabe-ops/startgg-oauth2-full/ci.yml?branch=main">
+  </a>
+  <a href="https://www.npmjs.com/package/startgg-oauth2-pkce">
+    <img alt="npm" src="https://img.shields.io/npm/v/startgg-oauth2-pkce">
+  </a>
+  <a href="./LICENSE">
+    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg">
+  </a>
+  <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18.0-brightgreen">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-blue">
+</p>
+
+# StartGG OAuth2 + PKCE Toolkit (TypeScript)
+
+Drop-in utilities for **OAuth 2.0 Authorization Code with PKCE** and **Bearer** usage against Start.gg (or any RFC-compliant OAuth2 provider).
+
+- ✅ RFCs: 6749 (OAuth2), 6750 (Bearer), 7636 (PKCE)
+- ✅ PKCE S256, high-entropy verifier
+- ✅ `application/x-www-form-urlencoded` token requests
+- ✅ Scope-safe validation (assume unchanged when `scope` omitted)
+- ✅ Robust error surfaces (JSON/text)
+- ✅ Skew-aware expiry helper (`BearerToken`)
+- ✅ Cross-env: Browser + Node (WebCrypto + `fetch`)
+- ✅ **CI**: Jest + TypeScript build on push/PR
+
+---
+
+Cooked for *you* by 0xabadbabe - using a lot of 💜 and few lines of code.
+... with hope tha this would help for any dev struggling with oauth2 start.gg specific.
+
+```fish
+startgg-oauth2-full@0.1.0 test
+> jest --runInBand pkce
+
+ PASS  __tests__/pkce.test.ts
+  PKCE helpers
+    ✓ generateCodeVerifier length bounds (4 ms)
+    ✓ computeCodeChallengeS256 deterministic (3 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       2 passed, 2 total
+Snapshots:   0 total
+Time:        1.121 s, estimated 2 s
+Ran all test suites matching /pkce/i.
+```
+
+## Installation
+
+```bash
+npm i startgg-oauth2-pkce
+# or copy src/auth/StartGGOAuth2.ts into your project
+```
+
+---
+
+## Requirements
+
+- Browser: `window.crypto.subtle`, `window.crypto.getRandomValues`, `fetch`
+- Node: **18+** (built-in WebCrypto + `fetch`)
+
+---
+
+## Quick Start
+
+### Browser (PKCE → Exchange)
+
+```ts
+import { buildAuthorizeUrl, StartGGScope } from 'startgg-oauth2-pkce';
+
+const cfg = {
+  clientId: '<client-id>',
+  authEndpoint: 'https://api.start.gg/oauth/authorize',
+  redirectUri: 'https://your.app/callback',
+};
+
+const { url, codeVerifier } = await buildAuthorizeUrl(cfg, {
+  scopes: [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL],
+  state: crypto.randomUUID(),
+});
+
+sessionStorage.setItem('pkce:verifier', codeVerifier);
+sessionStorage.setItem('oauth:state', '<same-state>');
+location.href = url;
+```
+
+### Callback (Exchange + Bearer)
+
+```ts
+import { createStartGGAuth2Handler, BearerToken, StartGGScope } from 'startgg-oauth2-pkce';
+
+const params = new URLSearchParams(location.search);
+const code = params.get('code')!;
+const state = params.get('state')!;
+if (state !== sessionStorage.getItem('oauth:state')) throw new Error('State mismatch');
+
+const handler = createStartGGAuth2Handler({
+  clientId: '<client-id>',
+  redirectUri: 'https://your.app/callback',
+  authEndpoint: 'https://api.start.gg/oauth/authorize',
+  tokenEndpoint: 'https://api.start.gg/oauth/token',
+});
+
+const res = await handler.exchangeToken(code, sessionStorage.getItem('pkce:verifier')!, [
+  StartGGScope.USER_IDENTITY,
+  StartGGScope.USER_EMAIL,
+]);
+
+const bearer = BearerToken.fromOAuthResponse(res);
+fetch('https://api.start.gg/your-endpoint', { headers: bearer.toAuthHeader() });
+```
+
+---
+
+## Scripts
+
+```bash
+npm run build      # tsc build
+npm test           # Jest tests (needs ts-node installed)
+```
+
+Examples ship as their own workspaces—hop into each folder, install once, then use the local scripts:
+
+- Browser (Vite): `cd examples/browser && npm install && npm run dev`
+- Node CLI/server: `cd examples/node && npm install && npm run dev`
+- Discord.js bot: `cd examples/discordjs && npm install && npm run dev`
+- Next.js app: `cd examples/nextjs && npm install && npm run dev`
+- Frontend Vite demo: `cd examples/vite && npm install && npm run dev`
+
+---
+
+## API (summary)
+
+- `generateCodeVerifier(len?: number): string`
+- `computeCodeChallengeS256(verifier: string): Promise<string>`
+- `buildAuthorizeUrl(cfg, opts): Promise<{ url, codeVerifier, codeChallenge }>`
+- `createStartGGAuth2Handler(cfg): StartGGOAuth2Handler`
+  - `exchangeToken(code, codeVerifier, expectedScopes)`
+  - `refreshToken(refreshToken, originalScopes)`
+- `BearerToken`
+  - `fromOAuthResponse(res, nowMs?, skewSeconds?)`
+  - `isExpired()`, `willExpireWithin()`, `toAuthHeader()`, `assertUsable()`
+
+### Scopes
+
+```ts
+enum StartGGScope {
+  USER_IDENTITY = 'user.identity',
+  USER_EMAIL = 'user.email',
+  TOURNAMENT_MANAGER = 'tournament.manager',
+  TOURNAMENT_REPORTER = 'tournament.reporter',
+}
+```
+
+---
+
+## Scope Semantics
+
+- If response **includes** `scope`, it’s validated; missing required → `ScopeValidationError`.
+- If response **omits** `scope`, treat as unchanged (RFC 6749).
+- Refresh: preserve prior `refresh_token` if omitted by server.
+
+---
+
+## Error Model
+
+```ts
+class OAuth2Error extends Error {
+  code?: string;     // e.g., TOKEN_EXCHANGE_FAILED
+  details?: unknown; // parsed JSON or { raw: string }
+}
+```
+
+---
+
+## Examples
+
+- Browser (Vite SPA): `examples/browser/`
+- Node CLI + redirect catcher: `examples/node/`
+- Discord bot (discord.js v14): `examples/discordjs/`
+- Next.js (App Router): `examples/nextjs/`
+- Frontend Vite scaffold: `examples/vite/`
+
+---
+
+## CI
+
+GitHub Actions runs TypeScript build + Jest on push/PR (Node 18 & 20). See `.github/workflows/ci.yml`.
+
+---
+
+## Repository Tree
+
+```text
+startgg-oauth2-full/
+├── README.md
+├── AGENTS.md
+├── LICENSE
+├── package.json
+├── tsconfig.json
+├── jest.config.ts
+├── jest.setup.ts
+├── .gitignore
+├── .npmrc
+├── src/
+│   └── auth/
+│       └── StartGGOAuth2.ts
+├── __tests__/
+│   ├── authorize-url.test.ts
+│   ├── bearer-token.test.ts
+│   ├── handler.test.ts
+│   └── pkce.test.ts
+├── examples/
+│   ├── browser/      # Vanilla browser Vite demo
+│   ├── node/         # CLI + local redirect server
+│   ├── discordjs/    # Discord bot OAuth flow
+│   ├── nextjs/       # Next.js App Router example
+│   └── vite/         # Minimal Vite SPA scaffold
+└── .github/
+    ├── ISSUE_TEMPLATE/
+    │   ├── bug_report.md
+    │   └── feature_request.md
+    └── workflows/
+        └── ci.yml
+```
+
+---
+
+## Security Notes
+
+- Use and verify `state`.
+- Keep `code_verifier` private.
+- Never log tokens; always HTTPS.
+
+---
+
+## License
+
+**MIT License**
+Copyright © 2025 0xABADBABE-ops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/STARTGG_OAUTH_SETUP.md

@@ -0,0 +1,41 @@
+# Start.gg OAuth Setup
+
+## 1) Create an OAuth app
+- In Start.gg developer console, create a **Public** OAuth app (PKCE).
+- Copy **Client ID**.
+
+## 2) Register redirect URIs
+Add exact matches you will use:
+- Browser demo: `http://localhost:5174/index.html` (or the exact URL you open)
+- Node catcher: `http://localhost:3000/callback`
+
+> Redirect URIs must match exactly (scheme/host/port/path).
+
+## 3) Scopes
+Common scopes:
+- `user.identity`
+- `user.email` (requires `user.identity`)
+- `tournament.manager`
+- `tournament.reporter`
+
+## 4) Environment variables (Node catcher)
+```bash
+export STARTGG_CLIENT_ID=your_client_id
+export STARTGG_AUTH_URL=https://api.start.gg/oauth/authorize
+export STARTGG_TOKEN_URL=https://api.start.gg/oauth/token
+npm run dev:node:server
+```
+
+## 5) Test the flow
+1. Ensure `http://localhost:3000/callback` is registered.
+2. Run the server script above.
+3. Browser opens Start.gg consent.
+4. Approve; you’re redirected to `/callback`.
+5. Terminal prints masked tokens + `Authorization` header.
+
+## 6) Production notes
+- Always HTTPS for redirects.
+- Persist and validate `state` (CSRF).
+- Keep `code_verifier` private (session/server).
+- Never log raw tokens in prod.
+- Plan for refresh token storage/rotation.

package/__tests__/authorize-url.test.ts

@@ -0,0 +1,62 @@
+import { buildAuthorizeUrl, StartGGScope } from '../src/auth/StartGGOAuth2';
+
+describe('Authorize URL', () => {
+  test('includes required params and scopes', async () => {
+    const cfg = {
+      clientId: 'abc',
+      authEndpoint: 'https://example.com/authorize',
+      redirectUri: 'https://app/callback',
+    };
+    const { url, codeVerifier, codeChallenge } = await buildAuthorizeUrl(cfg, {
+      scopes: [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL],
+      state: 'xyz',
+      prompt: 'consent',
+      extras: { access_type: 'offline' },
+    });
+
+    const u = new URL(url);
+    expect(u.searchParams.get('response_type')).toBe('code');
+    expect(u.searchParams.get('client_id')).toBe('abc');
+    expect(u.searchParams.get('redirect_uri')).toBe('https://app/callback');
+    expect(u.searchParams.get('scope')).toContain('user.identity');
+    expect(u.searchParams.get('scope')).toContain('user.email');
+    expect(u.searchParams.get('state')).toBe('xyz');
+    expect(u.searchParams.get('prompt')).toBe('consent');
+    expect(u.searchParams.get('access_type')).toBe('offline');
+    expect(u.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(codeVerifier.length).toBeGreaterThanOrEqual(43);
+    expect(codeChallenge.length).toBeGreaterThan(20);
+  });
+
+  test('throws when codeChallenge provided without matching codeVerifier', async () => {
+    const cfg = {
+      clientId: 'abc',
+      authEndpoint: 'https://example.com/authorize',
+      redirectUri: 'https://app/callback',
+    };
+    await expect(
+      buildAuthorizeUrl(cfg, {
+        scopes: [],
+        codeChallenge: 'custom-challenge',
+      })
+    ).rejects.toThrow(/codeVerifier is required/);
+  });
+
+  test('accepts externally provided PKCE pair when consistent', async () => {
+    const cfg = {
+      clientId: 'abc',
+      authEndpoint: 'https://example.com/authorize',
+      redirectUri: 'https://app/callback',
+    };
+    const verifier = 'test-verifier-1234567890_-=.~';
+    const expectedChallenge = 'xPCddgBLJpr4TYXpjK5OM51rAX0xrMyIOiVyy18DPQ8';
+    const result = await buildAuthorizeUrl(cfg, {
+      scopes: [],
+      codeVerifier: verifier,
+      codeChallenge: expectedChallenge,
+    });
+
+    expect(result.codeVerifier).toBe(verifier);
+    expect(result.codeChallenge).toBe(expectedChallenge);
+  });
+});

package/__tests__/bearer-token.test.ts

@@ -0,0 +1,21 @@
+import { BearerToken } from '../src/auth/StartGGOAuth2';
+
+describe('BearerToken', () => {
+  test('applies skew and expiry checks', () => {
+    const now = 1_000_000;
+    const res = {
+      access_token: 'at',
+      token_type: 'Bearer',
+      expires_in: 120,
+    };
+    const token = BearerToken.fromOAuthResponse(res as any, now, 60);
+    expect(token.isExpired(now)).toBe(false);
+    expect(token.willExpireWithin(120, now)).toBe(true);
+    expect(token.toAuthHeader()).toEqual({ Authorization: 'Bearer at' });
+  });
+
+  test('non-expiring when expires_in absent', () => {
+    const token = BearerToken.fromOAuthResponse({ access_token: 'at', token_type: 'Bearer' } as any, 0, 60);
+    expect(token.isExpired()).toBe(false);
+  });
+});

package/__tests__/handler.test.ts

@@ -0,0 +1,111 @@
+import {
+  createStartGGAuth2Handler,
+  StartGGScope,
+  OAuth2Error,
+} from '../src/auth/StartGGOAuth2';
+
+describe('StartGGOAuth2Handler', () => {
+  const cfg = {
+    clientId: 'client',
+    redirectUri: 'https://app/callback',
+    authEndpoint: 'https://example.com/authorize',
+    tokenEndpoint: 'https://example.com/token',
+  };
+
+  beforeEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('exchangeToken success with scope present', async () => {
+    const mockBody = {
+      access_token: 'at',
+      token_type: 'Bearer',
+      expires_in: 3600,
+      scope: 'user.identity user.email',
+      refresh_token: 'rt',
+    };
+    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
+      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
+    );
+
+    const handler = createStartGGAuth2Handler(cfg);
+    const res = await handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL]);
+    expect(res.access_token).toBe('at');
+    expect(res.refresh_token).toBe('rt');
+  });
+
+  test('exchangeToken accepts missing scope (assume unchanged)', async () => {
+    const mockBody = {
+      access_token: 'at',
+      token_type: 'Bearer',
+      expires_in: 3600,
+      refresh_token: 'rt',
+    };
+    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
+      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
+    );
+
+    const handler = createStartGGAuth2Handler(cfg);
+    const res = await handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY]);
+    expect(res.access_token).toBe('at');
+  });
+
+  test('exchangeToken fails when token_type not Bearer', async () => {
+    const mockBody = {
+      access_token: 'at',
+      token_type: 'MAC',
+      expires_in: 3600,
+      scope: 'user.identity',
+    };
+    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
+      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
+    );
+
+    const handler = createStartGGAuth2Handler(cfg);
+    await expect(handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY]))
+      .rejects.toThrow(OAuth2Error);
+  });
+
+  test('refreshToken preserves previous refresh_token when omitted', async () => {
+    const mockBody = {
+      access_token: 'at2',
+      token_type: 'Bearer',
+      expires_in: 3600,
+      scope: 'user.identity',
+    };
+    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
+      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
+    );
+
+    const handler = createStartGGAuth2Handler(cfg);
+    const res = await handler.refreshToken('rt-old', [StartGGScope.USER_IDENTITY]);
+    expect(res.refresh_token).toBe('rt-old');
+  });
+
+  test('refreshToken throws when scope reduced', async () => {
+    const mockBody = {
+      access_token: 'at3',
+      token_type: 'Bearer',
+      scope: 'user.identity',
+    };
+    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
+      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
+    );
+
+    const handler = createStartGGAuth2Handler(cfg);
+    await expect(
+      handler.refreshToken('rt', [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL])
+    ).rejects.toThrow('Missing required scopes: user.email');
+  });
+
+  test('handles non-JSON error body safely', async () => {
+    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
+      // @ts-ignore
+      new Response('<html>bad request</html>', { status: 400, headers: { 'Content-Type': 'text/html' } })
+    );
+
+    const handler = createStartGGAuth2Handler(cfg);
+    await expect(handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY]))
+      .rejects.toThrow('Token exchange failed');
+  });
+});

package/__tests__/pkce.test.ts

@@ -0,0 +1,17 @@
+import { computeCodeChallengeS256, generateCodeVerifier } from '../src/auth/StartGGOAuth2';
+
+describe('PKCE helpers', () => {
+  test('generateCodeVerifier length bounds', () => {
+    expect(generateCodeVerifier(10).length).toBeGreaterThanOrEqual(43);
+    expect(generateCodeVerifier(200).length).toBeLessThanOrEqual(128);
+  });
+
+  test('computeCodeChallengeS256 deterministic', async () => {
+    const verifier = 'test-verifier-1234567890_-=.~';
+    const ch1 = await computeCodeChallengeS256(verifier);
+    const ch2 = await computeCodeChallengeS256(verifier);
+    expect(ch1).toEqual(ch2);
+    expect(typeof ch1).toBe('string');
+    expect(ch1.length).toBeGreaterThan(20);
+  });
+});

package/examples/browser/README.md

@@ -0,0 +1,20 @@
+# Browser Demo
+
+This example runs the Start.gg OAuth helpers in a plain browser application with no framework. It uses Vite for bundling and serves a single page that builds PKCE authorize URLs, displays the verifier/challenge pair, and exchanges the authorization code after Start.gg redirects back.
+
+## Getting Started
+```bash
+cd examples/browser
+npm install
+npm run dev
+```
+
+The dev server opens at `http://localhost:5173`. Fill in your Start.gg OAuth client details and click **Generate Authorize URL**. Inspect the generated verifier/challenge values, open the authorize link in a new tab, and complete the Start.gg flow. When Start.gg redirects back, the page exchanges the code and prints a token summary.
+
+## Production Build
+```bash
+npm run build
+npm run preview
+```
+
+`npm run build` writes static assets to `dist/`, and `npm run preview` serves them locally.