startgg-oauth2-full 0.1.0 → 0.2.0

package/.github/workflows/release.yml

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

@@ -0,0 +1,46 @@
+# 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/README.md

@@ -4,8 +4,8 @@
   <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 href="https://www.npmjs.com/package/startgg-oauth2-full">
+    <img alt="npm" src="https://img.shields.io/npm/v/startgg-oauth2-full">
   </a>
   <a href="./LICENSE">
     <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg">
@@ -51,10 +51,19 @@ Ran all test suites matching /pkce/i.
 ## Installation
 
 ```bash
-npm i startgg-oauth2-pkce
+npm i startgg-oauth2-full
 # or copy src/auth/StartGGOAuth2.ts into your project
 ```
 
+### GitHub Packages (optional)
+
+This library is also mirrored to GitHub Packages if your environment prefers that registry:
+
+```bash
+npm set //npm.pkg.github.com/:_authToken=<GH_TOKEN_WITH_PACKAGES_SCOPE>
+npm install @0xabadbabe-ops/startgg-oauth2-full
+```
+
 ---
 
 ## Requirements
@@ -69,7 +78,7 @@ npm i startgg-oauth2-pkce
 ### Browser (PKCE → Exchange)
 
 ```ts
-import { buildAuthorizeUrl, StartGGScope } from 'startgg-oauth2-pkce';
+import { buildAuthorizeUrl, StartGGScope } from 'startgg-oauth2-full';
 
 const cfg = {
   clientId: '<client-id>',
@@ -90,7 +99,7 @@ location.href = url;
 ### Callback (Exchange + Bearer)
 
 ```ts
-import { createStartGGAuth2Handler, BearerToken, StartGGScope } from 'startgg-oauth2-pkce';
+import { createStartGGAuth2Handler, BearerToken, StartGGScope } from 'startgg-oauth2-full';
 
 const params = new URLSearchParams(location.search);
 const code = params.get('code')!;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "startgg-oauth2-full",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "scripts": {

package/tsconfig.json

@@ -18,8 +18,10 @@
   },
   "include": [
     "src",
-    "examples",
     "__tests__",
     "jest.setup.ts"
+  ],
+  "exclude": [
+    "examples"
   ]
 }