Merge pull request #1593 from pangeacyber/auth_docs

Update react-auth typedocs, use vanilla-js auth client, remove dead code

.github/workflows/ci.yml

@@ -89,6 +89,9 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4.2.1
 
+      - name: Enabled Corepack
+        run: corepack enable
+
       - name: Setup Node.js
         uses: actions/setup-node@v4.0.4
         with:
@@ -97,9 +100,7 @@ jobs:
           cache-dependency-path: ./packages/react-auth/yarn.lock
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
-
-      - run: yarn list
+        run: yarn install --immutable
 
       - name: Type check
         run: yarn typecheck

packages/react-auth/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

packages/react-auth/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.15] - 2024-10-11
+
+### Changed
+
+- Use @pangeacyber/vanilla-js auth client
+- Removed axios as dependency
+- Removed non-functional ComponentAuthProvider
+- Updated typedoc strings

packages/react-auth/README.md

@@ -1,5 +1,3 @@
-## Pangea React Auth
-
 ## Getting started
 
 ### Installation
@@ -16,16 +14,112 @@ Using [yarn](https://yarnpkg.com/)
 yarn add @pangeacyber/react-auth
 ```
 
-### Context Providers and Classes
+### Configure Pangea AuthN
+
+Enable the **AuthN Service** in the [Pangea Console](https://console.pangea.cloud).
+
+> **If you're using an existing application**, verify that you have configured the following settings for AuthN:
+>
+> - Under "Auth Methods", ensure "Password" authentication is enabled.
+> - Under "Redirects", configure a redirect that reflects the origin of your application. For local development that might be `http://localhost:3000`
+> - In the "Auth Settings" section, enable "Allow Signups".
+
+Take note of the **Domain**, **Client Token** and **Hosted Login** values in the "Configuration Details" panel on the "Overview" page. You'll need these values in the next step.
+
+### Configure the SDK
+
+Configure the SDK by wrapping your application in `AuthProvider`:
+
+```jsx
+// src/index.js
+import React from "react";
+import { useNavigate } from "react-router-dom";
+import { AuthProvider } from "@pangeacyber/react-auth";
+
+const App = () => {
+  const navigate = useNavigate();
+
+  return (
+    <AuthProvider
+      loginUrl="YOUR_HOSTED_LOGIN_URL"
+      config={{
+        domain: "YOUR_PANGEA_DOMAIN",
+        clientToken: "YOUR_CLIENT_TOKEN",
+      }}
+    >
+      <App />
+    </AuthProvider>
+  );
+};
+```
+
+Use the `useAuth` hook in your components to access authentication state.
+
+```jsx
+// src/App.js
+import React from "react";
+
+import { useAuth } from "@pangeacyber/react-auth";
+
+const App = () => {
+  const { authenticated, loading, error, user, login, logout } = useAuth();
+  const navigate = useNavigate();
+
+  if (loading) {
+    return <div>Loading</div>;
+  } else if (error) {
+    return <div>Error: {error}</div>;
+  }
+
+  if (authenticated) {
+    return (
+      <div>
+        Logged in as {user.profile.first_name}
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
+  } else {
+    return (
+      <div>
+        <button onClick={login}>Login</button>
+      </div>
+    );
+  }
+};
+
+export default App;
+```
+
+### Configuration Options
+
+Required Configuration
+
+- **loginUrl** The URL of the hosted login page
+- **config**
+  - **domain** The Pangea domain of the project
+  - **clientToken** A Pangea client access token
+
+Optional Configuration
+
+Additional `config` object parameters
+**config**
+
+- **callbackUri** The URI that the hosted page will redirect to after a login or logout. Defaults to `window.location.origin`.
+- **useJwt** Use JSON Web Tokens for authentication. The AuthN Service must all be configured to use JWTs.
+- **sessionKey** The key name used for session information. Defaults to `pangea-session`.
 
-- **[AuthProvider](src/AuthProvider)**
-  A content provider for adding authentication using Pangea hosted pages.
+Cookie configuration parameters
+**cookieOptions**
 
-- **[ComponentAuthProvider](src/ComponentAuthProvider)**
-  A context provider for implementing UI-only authentication using AuthN Flow endpoints.
+- **useCookie** The AuthProvider will store tokens using cookies and enable session sharing in a browser and across subdomains. Defaults to false.
+- **cookieMaxAge** The lifetime of session cookies in seconds. Defaults to 48 hours.
+- **cookieName** The name of the user token cookie. Defaults to `pangea-token`.
+- **refreshCookieName** The name of the refresh token cookie. Defaults to `pangea-refresh`.
+- **cookieDomain** The domain to set on the cookie.
 
-- **[AuthNClient](src/AuthNClient)**
-  A client class for using common AuthN client endpoints.
+Additional AuthProvider Props
 
-- **[AuthNFlow](src/AuthNFlow)**
-  A context provider and client for implementing authentication using AuthN Flow endpoints.
+- **onLogin** A function to call on successful login. Defaults to `undefined`.
+- **redirectPathname** A path to append to the redirectUri on successful login. Defaults to `undefined`.
+- **redirectOnLogout** When set to true, redirect to the hosted login page on logout. Defaults to `false`.
+- **useStrictStateCheck** Verify the state value on login. Defaults to `true`.

packages/react-auth/docs/01-index.md

@@ -2,18 +2,13 @@
 title: Overview
 displayed_sidebar: react-auth
 slug: /libraries/react-auth/
-description: Learn how to use the React Auth components from Pangea in your app
-# image: /img/og/open-graph-redact.jpg # TODO
+description: Learn how to use the React Auth component from Pangea in your app
 ---
 
-## Overview
-
-This React Auth package provides components and tools which can be used to provide your application with authentication powered by Pangea's AuthN service.
+This React Auth package provides a component which can be used to provide your application with authentication powered by Pangea's AuthN service.
 
 Pangea's AuthN service allows you to build a cloud-based authentication flow to help your login, session, and user management align with your security requirements while matching the look and feel of your app. The components and utilities in this package help you manage your application authentication sessions and state with AuthN.
 
-## Installation
-
 Using [npm](https://npmjs.org/)
 
 ```bash
@@ -26,20 +21,110 @@ Using [yarn](https://yarnpkg.com/)
 yarn add @pangeacyber/react-auth
 ```
 
-## Components
+### Configure Pangea AuthN
+
+Enable the **AuthN Service** in the [Pangea Console](https://console.pangea.cloud).
+
+> **If you're using an existing application**, verify that you have configured the following settings for AuthN:
+>
+> - Under "Auth Methods", ensure "Password" authentication is enabled.
+> - Under "Redirects", configure a redirect that reflects the origin of your application. For local development that might be `http://localhost:3000`
+> - In the "Auth Settings" section, enable "Allow Signups".
+
+Take note of the **Domain**, **Client Token** and **Hosted Login** values in the "Configuration Details" panel on the "Overview" page. You'll need these values in the next step.
+
+### Configure the SDK
+
+Configure the SDK by wrapping your application in `AuthProvider`:
+
+```jsx
+// src/index.js
+import React from "react";
+import { useNavigate } from "react-router-dom";
+import { AuthProvider } from "@pangeacyber/react-auth";
+
+const App = () => {
+  const navigate = useNavigate();
+
+  return (
+    <AuthProvider
+      loginUrl="YOUR_HOSTED_LOGIN_URL"
+      config={{
+        domain: "YOUR_PANGEA_DOMAIN",
+        clientToken: "YOUR_CLIENT_TOKEN",
+      }}
+    >
+      <App />
+    </AuthProvider>
+  );
+};
+```
+
+Use the `useAuth` hook in your components to access authentication state.
+
+```jsx
+// src/App.js
+import React from "react";
+
+import { useAuth } from "@pangeacyber/react-auth";
+
+const App = () => {
+  const { authenticated, loading, error, user, login, logout } = useAuth();
+  const navigate = useNavigate();
+
+  if (loading) {
+    return <div>Loading</div>;
+  } else if (error) {
+    return <div>Error: {error}</div>;
+  }
+
+  if (authenticated) {
+    return (
+      <div>
+        Logged in as {user.profile.first_name}
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
+  } else {
+    return (
+      <div>
+        <button onClick={login}>Login</button>
+      </div>
+    );
+  }
+};
+
+export default App;
+```
+
+### Configuration Options
+
+Required Configuration
 
-### [AuthProvider](./api-reference/#AuthProvider)
+- **loginUrl** The URL of the hosted login page
+- **config**
+  - **domain** The Pangea domain of the project
+  - **clientToken** A Pangea client access token
 
-A content provider for adding authentication using Pangea hosted pages.
+Optional Configuration
 
-### [ComponentAuthProvider](./api-reference/#ComponentAuthProvider)
+Additional **config** object parameters
 
-A context provider for implementing UI-only authentication using AuthN Flow endpoints.
+- **callbackUri** The URI that the hosted page will redirect to after a login or logout. Defaults to `window.location.origin`.
+- **useJwt** Use JSON Web Tokens for authentication. The AuthN Service must all be configured to use JWTs.
+- **sessionKey** The key name used for session information. Defaults to `pangea-session`.
 
-### [AuthNClient](./api-reference/#AuthNClient)
+Cookie configuration **cookieOptions** parameters
 
-A client class for using common AuthN client endpoints.
+- **useCookie** The AuthProvider will store tokens using cookies and enable session sharing in a browser and across subdomains. Defaults to false.
+- **cookieMaxAge** The lifetime of session cookies in seconds. Defaults to 48 hours.
+- **cookieName** The name of the user token cookie. Defaults to `pangea-token`.
+- **refreshCookieName** The name of the refresh token cookie. Defaults to `pangea-refresh`.
+- **cookieDomain** The domain to set on the cookie.
 
-### [AuthNFlow](./api-reference/#AuthNFlow)
+Additional AuthProvider Props
 
-A context provider and client for implementing authentication using AuthN Flow endpoints.
+- **onLogin** A function to call on successful login. Defaults to `undefined`.
+- **redirectPathname** A path to append to the redirectUri on successful login. Defaults to `undefined`.
+- **redirectOnLogout** When set to true, redirect to the hosted login page on logout. Defaults to `false`.
+- **useStrictStateCheck** Verify the state value on login. Defaults to `true`.

packages/react-auth/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pangeacyber/react-auth",
   "description": "Pangea auth provider React component",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "commonjs",
   "source": "src/index.ts",
   "main": "dist/index.cjs",
@@ -26,7 +26,7 @@
   "repository": "github:pangeacyber/pangea-javascript",
   "author": "Pangea (https://pangea.cloud)",
   "license": "MIT",
-  "packageManager": "yarn@1.22.22",
+  "packageManager": "yarn@4.5.0",
   "scripts": {
     "build": "yarn build-docs && parcel build && cp dist/index.d.ts dist/index.d.mts",
     "build-docs": "typedoc --plugin typedoc-plugin-rename-defaults",
@@ -36,7 +36,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "axios": "^1.7.7",
+    "@pangeacyber/vanilla-js": "^0.1.11",
     "jose": "^5.9.3",
     "lodash": "^4.17.21"
   },
@@ -46,7 +46,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.16.4",
-    "@babel/core": "^7.25.7",
+    "@babel/core": "^7.25.8",
     "@futureportal/parcel-transformer-package-version": "^1.0.0",
     "@parcel/config-default": "^2.12.0",
     "@parcel/packager-ts": "^2.12.0",
@@ -62,6 +62,6 @@
     "react": "^18.3.1",
     "typedoc": "^0.26.8",
     "typedoc-plugin-rename-defaults": "^0.7.1",
-    "typescript": "^5.6.2"
+    "typescript": "^5.6.3"
   }
 }