startgg-oauth2-full 0.2.0 → 0.2.2

package/dist/auth/StartGGOAuth2.js

@@ -0,0 +1,306 @@
+import { STARTGG_ENDPOINTS } from "../constants";
+// Full RFC-compliant implementation
+// of OAuth2 Authorization Code Flow with PKCE (RFC 6749, RFC 7636)
+// for Start.gg API (https://start.gg/docs/oauth2).
+// Happy to accept PRs for improvements or fixes!
+// (c) 2026 0xabadbabe (jet'aime), Inc. (MIT License)
+// Happy coding! <3
+export var StartGGScope;
+(function (StartGGScope) {
+    StartGGScope["USER_IDENTITY"] = "user.identity";
+    StartGGScope["USER_EMAIL"] = "user.email";
+    StartGGScope["TOURNAMENT_MANAGER"] = "tournament.manager";
+    StartGGScope["TOURNAMENT_REPORTER"] = "tournament.reporter";
+})(StartGGScope || (StartGGScope = {}));
+export class OAuth2Error extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = "OAuth2Error";
+        this.code = code;
+        this.details = details;
+    }
+}
+export class ScopeValidationError extends OAuth2Error {
+    requestedScopes;
+    grantedScopes;
+    constructor(message, requestedScopes, grantedScopes) {
+        super(message, "SCOPE_VALIDATION_FAILED");
+        this.requestedScopes = requestedScopes;
+        this.grantedScopes = grantedScopes;
+    }
+}
+/** WebCrypto subtle (browser + Node >=18). */
+async function getSubtleCrypto() {
+    const g = globalThis;
+    if (g.crypto?.subtle)
+        return g.crypto.subtle;
+    throw new OAuth2Error("WebCrypto subtle not available; required for PKCE S256", "CRYPTO_UNAVAILABLE");
+}
+/** Base64 (Buffer if available, else btoa path). */
+function base64Encode(bytes) {
+    const g = globalThis;
+    if (typeof g.Buffer?.from === "function")
+        return g.Buffer.from(bytes).toString("base64");
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk)
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    if (typeof g.btoa !== "function")
+        throw new OAuth2Error("btoa not available for base64 encoding", "B64_UNAVAILABLE");
+    return g.btoa(binary);
+}
+/** URL-safe Base64 (no padding). */
+function base64Url(bytes) {
+    const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    return base64Encode(u8)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+}
+/** Random bytes using WebCrypto. */
+function getRandomBytes(length) {
+    const g = globalThis;
+    if (!g.crypto?.getRandomValues)
+        throw new OAuth2Error("crypto.getRandomValues unavailable", "RNG_UNAVAILABLE");
+    const bytes = new Uint8Array(length);
+    g.crypto.getRandomValues(bytes);
+    return bytes;
+}
+/** x-www-form-urlencoded body. */
+function formBody(params) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        sp.set(k, v);
+    return sp.toString();
+}
+/** Parse non-JSON error bodies safely. */
+async function parseJsonSafe(res) {
+    const txt = await res.text();
+    try {
+        return JSON.parse(txt);
+    }
+    catch {
+        return { raw: txt };
+    }
+}
+/** Validate token response + Bearer type. */
+function validateTokenResponse(tr) {
+    if (!tr || typeof tr !== "object")
+        throw new OAuth2Error("Invalid token response shape", "INVALID_TOKEN_RESPONSE", tr);
+    if (!tr.access_token)
+        throw new OAuth2Error("Missing access_token", "INVALID_TOKEN_RESPONSE", tr);
+    if (!tr.token_type || tr.token_type.toLowerCase() !== "bearer") {
+        throw new OAuth2Error("Unsupported token_type", "UNSUPPORTED_TOKEN_TYPE", tr);
+    }
+}
+/** If scope omitted, assume unchanged (RFC 6749). */
+function validateScopesOrAssumePrevious(responseScope, requiredScopes) {
+    if (!requiredScopes.length)
+        return;
+    if (responseScope == null)
+        return;
+    const granted = new Set(responseScope.split(/\s+/).filter(Boolean));
+    const missing = requiredScopes.filter((s) => !granted.has(s));
+    if (missing.length > 0) {
+        throw new ScopeValidationError(`Missing required scopes: ${missing.join(", ")}`, requiredScopes, Array.from(granted));
+    }
+}
+/** Fetch with timeout to avoid hangs. */
+async function fetchWithTimeout(input, init = {}) {
+    const { timeoutMs = 15000, ...rest } = init;
+    const ac = new AbortController();
+    const id = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        return await fetch(input, { ...rest, signal: ac.signal });
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+// -------- PKCE (RFC 7636) --------
+const PKCE_VERIFIER_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+export function generateCodeVerifier(length = 64) {
+    const len = Math.min(Math.max(length, 43), 128);
+    const alphabet = PKCE_VERIFIER_CHARS;
+    const alphabetLength = alphabet.length;
+    const maxValue = Math.floor(256 / alphabetLength) * alphabetLength;
+    const result = [];
+    while (result.length < len) {
+        const randomBytes = getRandomBytes(len - result.length);
+        for (const byte of randomBytes) {
+            if (byte >= maxValue)
+                continue; // Skip to avoid modulo bias.
+            result.push(alphabet.charAt(byte % alphabetLength));
+            if (result.length === len)
+                break;
+        }
+    }
+    return result.join("");
+}
+/** S256 challenge for a verifier. */
+export async function computeCodeChallengeS256(codeVerifier) {
+    const enc = new TextEncoder();
+    const subtle = await getSubtleCrypto();
+    const hash = await subtle.digest("SHA-256", enc.encode(codeVerifier));
+    return base64Url(hash);
+}
+/** Build an authorization URL with PKCE (S256). */
+export async function buildAuthorizeUrl(cfg, opts) {
+    let codeVerifier;
+    let codeChallenge;
+    if (opts.codeVerifier && opts.codeChallenge) {
+        const expectedChallenge = await computeCodeChallengeS256(opts.codeVerifier);
+        if (expectedChallenge !== opts.codeChallenge) {
+            throw new OAuth2Error("Provided codeChallenge does not match codeVerifier", "INVALID_PKCE_PAIR");
+        }
+        codeVerifier = opts.codeVerifier;
+        codeChallenge = opts.codeChallenge;
+    }
+    else if (opts.codeVerifier) {
+        codeVerifier = opts.codeVerifier;
+        codeChallenge = await computeCodeChallengeS256(codeVerifier);
+    }
+    else if (opts.codeChallenge) {
+        throw new OAuth2Error("codeVerifier is required when providing codeChallenge", "INVALID_PKCE_PAIR");
+    }
+    else {
+        codeVerifier = generateCodeVerifier();
+        codeChallenge = await computeCodeChallengeS256(codeVerifier);
+    }
+    const u = new URL(cfg.authEndpoint);
+    const params = {
+        response_type: "code",
+        client_id: cfg.clientId,
+        redirect_uri: cfg.redirectUri,
+        scope: opts.scopes.map(String).join(" "),
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+    };
+    if (opts.state)
+        params.state = opts.state;
+    if (opts.prompt)
+        params.prompt = opts.prompt;
+    if (opts.extras) {
+        for (const [k, v] of Object.entries(opts.extras))
+            if (v != null)
+                params[k] = String(v);
+    }
+    for (const [k, v] of Object.entries(params))
+        u.searchParams.set(k, v);
+    return { url: u.toString(), codeVerifier, codeChallenge };
+}
+// -------- Bearer Token Helper (RFC 6750) --------
+export class BearerToken {
+    accessToken;
+    tokenType;
+    refreshToken;
+    expiresAt; // epoch ms
+    constructor(init) {
+        this.accessToken = init.accessToken;
+        this.tokenType = init.tokenType;
+        this.refreshToken = init.refreshToken;
+        this.expiresAt = init.expiresAt;
+    }
+    static fromOAuthResponse(res, nowMs = Date.now(), skewSeconds = 60) {
+        validateTokenResponse(res);
+        const expiresAt = typeof res.expires_in === "number"
+            ? nowMs +
+                Math.max(0, (res.expires_in - Math.max(0, skewSeconds)) * 1000)
+            : undefined;
+        return new BearerToken({
+            accessToken: res.access_token,
+            tokenType: "Bearer",
+            refreshToken: res.refresh_token,
+            expiresAt,
+        });
+    }
+    isExpired(nowMs = Date.now()) {
+        if (this.expiresAt == null)
+            return false; // unknown → treat as non-expiring
+        return nowMs >= this.expiresAt;
+    }
+    willExpireWithin(seconds, nowMs = Date.now()) {
+        if (this.expiresAt == null)
+            return false;
+        return this.expiresAt - nowMs <= seconds * 1000;
+    }
+    toAuthHeader() {
+        return { Authorization: `Bearer ${this.accessToken}` };
+    }
+    assertUsable(nowMs = Date.now()) {
+        if (this.isExpired(nowMs))
+            throw new OAuth2Error("Access token expired", "TOKEN_EXPIRED");
+    }
+}
+// -------- Handler (RFC 6749 §4.1.3, §6) --------
+export class StartGGOAuth2Handler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Exchange authorization code for tokens (PKCE). */
+    async exchangeToken(code, codeVerifier, expectedScopes) {
+        const tokenRequest = {
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: this.config.redirectUri,
+            code_verifier: codeVerifier,
+            client_id: this.config.clientId,
+        };
+        const res = await fetchWithTimeout(this.config.tokenEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: formBody(tokenRequest),
+            timeoutMs: this.config.fetchTimeoutMs ?? 15000,
+        });
+        if (!res.ok) {
+            const details = await parseJsonSafe(res);
+            throw new OAuth2Error("Token exchange failed", "TOKEN_EXCHANGE_FAILED", details);
+        }
+        const tokenResponse = (await res.json());
+        validateTokenResponse(tokenResponse);
+        validateScopesOrAssumePrevious(tokenResponse.scope, expectedScopes.map(String));
+        return tokenResponse;
+    }
+    /** Refresh access token; preserve prior refresh token if server omits rotation.
+     * Per RFC 6749, scope should only be included when requesting a subset of original scopes. */
+    async refreshToken(refreshToken, originalScopes) {
+        const refreshRequest = {
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: this.config.clientId,
+        };
+        const res = await fetchWithTimeout(this.config.tokenEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: formBody(Object.fromEntries(Object.entries(refreshRequest).filter(([, v]) => v != null))),
+            timeoutMs: this.config.fetchTimeoutMs ?? 15000,
+        });
+        if (!res.ok) {
+            const details = await parseJsonSafe(res);
+            throw new OAuth2Error("Token refresh failed", "TOKEN_REFRESH_FAILED", details);
+        }
+        const tokenResponse = (await res.json());
+        validateTokenResponse(tokenResponse);
+        validateScopesOrAssumePrevious(tokenResponse.scope, originalScopes.map(String));
+        if (!tokenResponse.refresh_token)
+            tokenResponse.refresh_token = refreshToken;
+        return tokenResponse;
+    }
+}
+/** Factory */
+export function createStartGGAuth2Handler(params) {
+    return new StartGGOAuth2Handler({
+        ...params,
+        authEndpoint: params.authEndpoint ?? STARTGG_ENDPOINTS.authorize,
+        tokenEndpoint: params.tokenEndpoint ?? STARTGG_ENDPOINTS.token,
+    });
+}

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const STARTGG_ENDPOINTS: {
+    readonly authorize: "https://api.start.gg/oauth/authorize";
+    readonly token: "https://api.start.gg/oauth/access_token";
+    readonly refresh: "https://api.start.gg/oauth/refresh";
+    readonly gql: "https://api.start.gg/gql/alpha";
+};
+export declare const STARTGG_SCOPES: readonly ["user.identity", "user.email", "tournament.manager", "tournament.reporter"];
+export declare const STARTGG_GQL_AUTH_HEADER: "Bearer";
+export type StartGGScopeValue = (typeof STARTGG_SCOPES)[number];
+export declare function isValidStartGGScope(scope: string): scope is StartGGScopeValue;

package/dist/constants.js

@@ -0,0 +1,16 @@
+export const STARTGG_ENDPOINTS = {
+    authorize: "https://api.start.gg/oauth/authorize",
+    token: "https://api.start.gg/oauth/access_token",
+    refresh: "https://api.start.gg/oauth/refresh",
+    gql: "https://api.start.gg/gql/alpha",
+};
+export const STARTGG_SCOPES = [
+    "user.identity",
+    "user.email",
+    "tournament.manager",
+    "tournament.reporter",
+];
+export const STARTGG_GQL_AUTH_HEADER = "Bearer";
+export function isValidStartGGScope(scope) {
+    return STARTGG_SCOPES.includes(scope);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./auth/StartGGOAuth2.js";
+export * from "./constants.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./auth/StartGGOAuth2.js";
+export * from "./constants.js";

package/package.json

@@ -1,24 +1,65 @@
 {
-  "name": "startgg-oauth2-full",
-  "version": "0.2.0",
-  "type": "module",
-  "license": "MIT",
-  "scripts": {
-    "dev:browser": "serve examples/browser -p 5174",
-    "dev:node": "tsx examples/node/index.ts",
-    "dev:node:server": "tsx examples/node/server.ts",
-    "test": "jest --runInBand",
-    "build": "tsc -p tsconfig.json"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "@types/node": "^22.7.5",
-    "jest": "^29.7.0",
-    "node-fetch": "^3.3.2",
-    "serve": "^14.2.1",
-    "ts-jest": "^29.2.5",
-    "ts-node": "10.9.2",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.3"
-  }
+	"name": "startgg-oauth2-full",
+	"version": "0.2.2",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./auth": {
+			"types": "./dist/auth/StartGGOAuth2.d.ts",
+			"import": "./dist/auth/StartGGOAuth2.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/0xABADBABE-ops/startgg-oauth2-full.git"
+	},
+	"scripts": {
+		"dev:browser": "serve examples/browser -p 5174",
+		"dev:node": "tsx examples/node/src/index.ts",
+		"dev:node:server": "tsx examples/node/src/server.ts",
+		"dev:vite": "cd examples/vite && npm run dev",
+		"dev:nextjs": "cd examples/nextjs && npm run dev",
+		"dev:discord": "cd examples/discordjs && npm run dev",
+		"build:vercel-connect": "cd packages/startgg-vercel-connect && npm run build",
+		"test": "jest --runInBand",
+		"test:watch": "jest --watch",
+		"test:coverage": "jest --coverage",
+		"lint": "tsc --noEmit",
+		"build": "tsc -p tsconfig.json",
+		"prepare": "npm run build"
+	},
+	"devDependencies": {
+		"@types/jest": "^29.5.12",
+		"@types/node": "^22.7.5",
+		"jest": "^29.7.0",
+		"lantern": "0.1.2",
+		"node-fetch": "^3.3.2",
+		"serve": "^14.2.6",
+		"ts-jest": "^29.2.5",
+		"ts-node": "10.9.2",
+		"tsx": "^4.19.0",
+		"typescript": "^5.6.3"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"allowScripts": {
+		"esbuild@0.25.11": true
+	}
 }

package/.github/ISSUE_TEMPLATE/bug_report.md

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

package/.github/ISSUE_TEMPLATE/feature_request.md

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

package/.github/pull_request_template.md

@@ -1,30 +0,0 @@
-# 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

@@ -1,23 +0,0 @@
-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/.github/workflows/release.yml

@@ -1,60 +0,0 @@
-name: Release Publish
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch:
-
-jobs:
-  publish:
-    name: Publish to npm
-    if: github.event.release.draft == false && github.event.release.prerelease == false || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Verify tag matches package version
-        if: github.event_name == 'release'
-        run: |
-          TAG="${{ github.event.release.tag_name }}"
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          if [ "$TAG" != "v$PKG_VERSION" ]; then
-            echo "Release tag $TAG does not match package version $PKG_VERSION"
-            exit 1
-          fi
-
-      - name: Build
-        run: npm run build
-
-      - name: Test
-        run: npm test -- --ci
-
-      - name: Publish
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish to GitHub Packages
-        env:
-          NODE_AUTH_TOKEN: ${{ github.token }}
-        run: |
-          ORIGINAL_NAME=$(node -p "require('./package.json').name")
-          OWNER_SCOPE=$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')
-          SCOPED_NAME="@${OWNER_SCOPE}/startgg-oauth2-full"
-          npm pkg set name="$SCOPED_NAME"
-          npm publish --registry https://npm.pkg.github.com
-          npm pkg set name="$ORIGINAL_NAME"

package/AGENTS.md

@@ -1,46 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- `src/` contains the TypeScript OAuth2 helpers (PKCE generation, token exchange, authorize URL builder).
-- `__tests__/` mirrors the source with Jest specs (e.g., `pkce.test.ts`, `authorize-url.test.ts`).
-- `examples/` includes Node, server, and browser demos; use them to validate end-to-end flows.
-- Root config (`tsconfig.json`, `jest.config.ts`, `package.json`) defines tooling standards—change only with consensus.
-
-## Build, Test, and Development Commands
-- `npm run build` compiles TypeScript via `tsc`; run before opening a PR.
-- `npm test` runs the full Jest suite; add `-- pkce` (or similar) to target individual specs.
-- `npm run dev:node`, `npm run dev:node:server`, and `npm run dev:browser` start interactive demos for manual OAuth verification.
-
-## Coding Style & Naming Conventions
-- Write modern TypeScript (ES2022 target) with strict null checks enabled in `tsconfig.json`.
-- Use two-space indentation, semicolons, and single quotes to match the existing codebase.
-- Functions and variables use `camelCase`, classes and enums use `PascalCase`, constants use `SCREAMING_SNAKE_CASE` where appropriate.
-- Prefer small, self-documenting helpers; add concise comments only when logic is non-obvious.
-
-## Testing Guidelines
-- Jest with `ts-jest` handles unit tests; new behaviour requires corresponding specs in `__tests__/`.
-- Name test files after the module under test (e.g., `foo.test.ts`); keep describe blocks aligned with exported functions.
-- Ensure deterministic randomness in tests (stub RNGs) and cover error cases like PKCE validation failures.
-
-## Commit & Pull Request Guidelines
-- Craft commits in the form `type(scope): summary` (examples in history: `fix(pkce): cap verifier length`).
-- Each PR should explain the change, list validation steps (e.g., `npm test` output), and link related issues or tickets.
-- Include screenshots or curl transcripts when work affects interactive flows or API responses.
-
-## Security & Configuration Tips
-- PKCE relies on WebCrypto; document fallbacks if new runtimes lack `crypto.subtle`.
-- Never log tokens or verifiers in examples; scrub debug statements before merging.
-- Keep secrets out of version control and reference sample env files instead.
-
-## Agent Workflow Checklist
-- Sync `main`, install modules (`npm install`), and confirm `npm run build` passes.
-- Add focused Jest coverage for new logic and ensure `npm test` is green.
-- Update docs (`README.md`, `AGENTS.md`) when behaviour or workflows shift.
-- Capture manual verification steps (demo URLs, curl output) in the PR description.
-
-## Release Process
-- Bump `package.json` version and update changelog/notes as needed.
-- Commit and tag in `vX.Y.Z` form, then push the tag (`git push origin vX.Y.Z`).
-- Create a GitHub release using that tag; the `Release Publish` workflow runs automatically (or run it manually via **Run workflow**).
-- Ensure `NPM_TOKEN` is configured as a repository secret with publish rights to npm.
-- The workflow also publishes to GitHub Packages using `GITHUB_TOKEN`; consumers can install via `npm install @${repo_owner}/startgg-oauth2-full`.

package/CONTRIBUTING.md

@@ -1,36 +0,0 @@
-# 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