@abaxx_tech/v-integration-react 1.1.0

package/README.md

@@ -0,0 +1,324 @@
+# v-integration-react
+`v-integration-react` is an npm library that provides React components for handling Verifier+ authentication UI.
+<br/><br/>
+
+## Features
+- **Verifier Authentication**: Pre-built authentication UI component with complete login flow.
+- **Modular Components**: Separate QR code and email authentication components.
+- **Token Management**: Provides authentication token through React Context.
+- **Real-time Authentication**: Server-Sent Events (SSE) for real-time authentication status updates.
+- **PKCE Flow**: Implements OAuth 2.0 PKCE (Proof Key for Code Exchange) for secure authentication.
+- **Error Handling**: Comprehensive error handling and user feedback.
+- **Customizable Styling**: Full control over colors, sizes, and text with support for both Tailwind classes and hex colors.
+- **Background Authentication Service**: Automatic token management and authentication flow handling.
+<br/><br/>
+
+## Installation
+Install the package via npm or yarn:
+```sh
+npm install @abaxxtech/v-integration-react@1.1.0
+# or
+yarn add @abaxxtech/v-integration-react@1.1.0
+```
+<br/><br/>
+
+## Usage
+### 1. Wrap your app with `VerifierProvider`
+Wrap your application with `VerifierProvider` to manage authentication. The provider automatically handles PKCE generation, SSE connections, and token management through the `AuthService`.
+```ts
+import { VerifierProvider } from "@abaxxtech/v-integration-react";
+
+const App = () => {
+  return (
+    <VerifierProvider
+      appId={Number(import.meta.env.VITE_APP_ID)}
+      apiUrl={import.meta.env.VITE_API_URL}
+      clientId={import.meta.env.VITE_CLIENT_ID}
+    >
+      {/* Your app goes here */}
+    </VerifierProvider>
+  );
+};
+
+export default App;
+```
+
+### 2. Choose your authentication component
+
+#### Complete Authentication UI (`VerifierAuth`)
+```ts
+import { VerifierAuth } from "@abaxxtech/v-integration-react";
+import "v-integration-react/index.css";
+
+const LoginPage = () => {
+  return <VerifierAuth title="Abaxx Drive" />;
+};
+
+export default LoginPage;
+```
+
+#### QR Code Only (`VerifierAuthQr`)
+```ts
+import { VerifierAuthQr } from "@abaxxtech/v-integration-react";
+import "v-integration-react/index.css";
+
+const QRLoginAuth = () => {
+  return (
+    <VerifierAuthQr 
+      size={150}
+      qrColor="#e60100"
+      checkmarkColor="#0b981"
+      showStatus={true}
+    />
+  );
+};
+
+export default QRLoginAuth;
+```
+
+#### Email Input Only (`VerifierAuthEmail`)
+```ts
+import { VerifierAuthEmail } from "@abaxxtech/v-integration-react";
+import "v-integration-react/index.css";
+
+const EmailLoginAuth = () => {
+  return (
+    <VerifierAuthEmail 
+      inputPlaceholder="Enter your email"
+      buttonText="Sign In"
+      buttonBackgroundColor="#0b981"
+      checkmarkColor="#0b981"
+    />
+  );
+};
+
+export default EmailLoginAuth;
+```
+
+* Import `v-integration-react/index.css` for the login UI styling.
+* All components provide authentication UI for Verifier+.
+* Each component can be customized with different props.
+
+### 3. Access authentication data through Context
+```ts
+import { useContext } from 'react';
+import { VContext } from 'v-integration-react';
+
+const MyComponent = () => {
+  const { 
+    token, 
+    identity, 
+    isAuthenticating, 
+    authRequestId,
+    authRequestIdExpires,
+    codeChallenge,
+    authError 
+  } = useContext(VContext);
+  
+  if (isAuthenticating) {
+    return <div>Authenticating...</div>;
+  }
+  
+  if (authError) {
+    return <div>Authentication Error: {authError}</div>;
+  }
+  
+  if (token) {
+    return <div>Authenticated! Token: {token}</div>;
+  }
+  
+  return <div>Not authenticated</div>;
+};
+```
+<br/><br/>
+
+## Components
+
+### `VerifierProvider`
+The main provider component that wraps your application and manages the authentication context. It automatically includes the `AuthService` component for handling background authentication processes.
+
+#### Props:
+| Prop | Type | Description |
+| ------------- | ------------- | ------------- |
+| `appId` | `string \| number`  | Unique application ID |
+| `apiUrl` | `string`  | API URL for authentication |
+| `clientId` | `string`  | Client identifier |
+| `children` | `ReactNode`  | Child components to be wrapped |
+
+#### Features:
+- Automatically generates PKCE code verifier and challenge
+- Establishes SSE connection for real-time authentication updates
+- Manages authentication state and token lifecycle
+- Handles authentication errors and provides error context
+
+### `VerifierAuth`
+Complete authentication UI with QR code and email input. This component provides a full-screen authentication experience with background image and branding.
+
+#### Props:
+| Prop | Type | Description |
+| ------------- | ------------- | ------------- |
+| `title` | `string`  | Title displayed in the login UI |
+| `containerClass` | `string`  | Additional CSS classes for the container |
+
+#### Features:
+- Full-screen authentication layout with background image
+- QR code generation with Abaxx branding
+- Email/Abaxx ID input field
+- Real-time authentication status updates
+- Loading states and error handling
+- Responsive design with grid layout
+
+### `VerifierAuthQr`
+QR code authentication component only. Displays a QR code that users can scan with the Verifier+ app for authentication.
+
+#### Props:
+| Prop | Type | Default | Description |
+| ------------- | ------------- | ------------- | ------------- |
+| `size` | `number` | `130` | QR code size in pixels |
+| `qrColor` | `string` | `"#e60100"` | QR code foreground color |
+| `logoImage` | `string` | `"https://content.abaxx.com/assets/static/qr-logo.png"` | Logo URL to display in QR center |
+| `logoWidth` | `number` | `40` | Logo width in pixels |
+| `logoHeight` | `number` | `20` | Logo height in pixels |
+| `quietZone` | `number` | `0` | Quiet zone around QR code |
+| `containerClass` | `string` | `""` | Additional CSS classes for container |
+| `showStatus` | `boolean` | `true` | Whether to show authentication status (success/pending) |
+| `checkmarkColor` | `string` | `"#c40808"` | Color of the checkmark icon (hex color) |
+
+#### Features:
+- Dynamic QR code generation with authentication parameters
+- Loading spinner while QR code is being generated
+- Optional status display with success/pending states
+- Customizable styling and branding
+- Automatic QR code updates when authentication parameters change
+
+### `VerifierAuthEmail`
+Email input authentication component only. Provides a standalone email/Abaxx ID input field with authentication functionality.
+
+#### Props:
+| Prop | Type | Default | Description |
+| ------------- | ------------- | ------------- | ------------- |
+| `inputPlaceholder` | `string` | `"Enter Email or Abaxx ID"` | Placeholder text for the input field |
+| `buttonText` | `string` | `"Sign In"` | Text displayed on the button |
+| `inputHeight` | `string` | `"v-h-10"` | Height class for the input field |
+| `inputWidth` | `string` | `"v-w-full"` | Width class for the input field |
+| `inputTextColor` | `string` | `"v-text-gray-600"` | Text color for the input field (Tailwind class or hex color) |
+| `inputBorderColor` | `string` | `"v-border-gray-400"` | Border color for the input field (Tailwind class or hex color) |
+| `inputBackgroundColor` | `string` | `"v-bg-transparent"` | Background color for the input field (Tailwind class or hex color) |
+| `buttonHeight` | `string` | `"v-h-10"` | Height class for the button |
+| `buttonWidth` | `string` | `"v-w-full"` | Width class for the button |
+| `buttonBackgroundColor` | `string` | `"v-bg-red"` | Background color for the button (Tailwind class or hex color) |
+| `buttonTextColor` | `string` | `"v-text-white"` | Text color for the button (Tailwind class or hex color) |
+| `containerClass` | `string` | `""` | Additional CSS classes for the container |
+| `checkmarkColor` | `string` | `"#c40808"` | Color of the checkmark icon (hex color) |
+
+#### Features:
+- Email/Abaxx ID input validation
+- Loading states with spinner animation
+- Real-time authentication status updates
+- Customizable styling with support for both Tailwind classes and hex colors
+- Error handling with user feedback
+- Success state with checkmark icon
+
+## Context API
+
+### `VContext`
+The authentication context provides access to all authentication-related state and functions.
+
+#### Available Properties:
+| Property | Type | Description |
+| ------------- | ------------- | ------------- |
+| `appId` | `string \| number` | Application ID |
+| `apiUrl` | `string` | API base URL |
+| `clientId` | `string` | Client identifier |
+| `identity` | `string` | User identity after authentication |
+| `authRequestId` | `string` | Current authentication request ID |
+| `authRequestIdExpires` | `Date` | Expiration time for the auth request |
+| `isAuthenticating` | `boolean` | Whether authentication is in progress |
+| `codeVerifier` | `string` | PKCE code verifier |
+| `codeChallenge` | `string` | PKCE code challenge |
+| `authCode` | `string` | Authorization code from successful auth |
+| `token` | `string \| null` | Authentication token |
+| `authError` | `string \| null` | Authentication error message |
+
+## Authentication Flow
+
+The library implements a complete OAuth 2.0 PKCE flow with the following steps:
+
+1. **PKCE Generation**: Automatically generates code verifier and challenge
+2. **SSE Connection**: Establishes Server-Sent Events connection for real-time updates
+3. **QR Code Generation**: Creates QR code with authentication parameters
+4. **User Authentication**: User scans QR code or enters email/Abaxx ID
+5. **Authorization**: Verifier+ app approves the authentication request
+6. **Token Exchange**: Exchanges authorization code for access token
+7. **State Management**: Updates authentication state throughout the process
+
+## Usage Examples
+
+### Custom Styling with Hex Colors
+```tsx
+// Custom green theme
+<VerifierAuthEmail 
+  inputPlaceholder="Enter your email address"
+  buttonText="Login Now"
+  inputHeight="v-h-12"
+  inputWidth="v-w-80"
+  inputTextColor="#0b981"
+  inputBorderColor="#0b981"
+  inputBackgroundColor="#f0f9ff"
+  buttonHeight="v-h-12"
+  buttonWidth="v-w-80"
+  buttonBackgroundColor="#0b981"
+  buttonTextColor="#ffffff"
+  checkmarkColor="#0b981"
+  containerClass="flex justify-center"
+/>
+
+// Custom QR with green theme
+<VerifierAuthQr 
+  size={150}
+  qrColor="#0b981"
+  checkmarkColor="#0b981"
+  showStatus={true}
+  containerClass="flex justify-center"
+/>
+```
+
+### Using Tailwind Classes
+```tsx
+// Tailwind-based styling
+<VerifierAuthEmail 
+  inputPlaceholder="Enter your email address"
+  buttonText="Login Now"
+  inputHeight="v-h-12"
+  inputWidth="v-w-80"
+  inputTextColor="v-text-blue-600"
+  inputBorderColor="v-border-blue-400"
+  inputBackgroundColor="v-bg-blue-50"
+  buttonHeight="v-h-12"
+  buttonWidth="v-w-80"
+  buttonBackgroundColor="v-bg-blue-600"
+  buttonTextColor="v-text-white"
+  containerClass="flex justify-center"
+/>
+```
+
+<br/>
+
+## 🔧 Environment Variables
+Make sure you define your environment variables in a `.env` file:
+```ini
+VITE_APP_ID="your-app-id"
+VITE_API_URL="your-api-url"
+VITE_CLIENT_ID="your-client-id"
+```
+
+**Note**: `VITE_APP_ID` can be either a string or number, and will be automatically converted to the appropriate type when passed to the `VerifierProvider`.
+<br/><br/>
+
+## 🛠 Development
+1. Clone the repo.
+2. Run `npm install` or `yarn install`.
+3. Start development:
+```sh
+npm run dev
+```

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@abaxx_tech/v-integration-react",
+  "version": "1.1.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abaxxtech/v-integration-react.git"
+  },
+  "type": "module",
+  "license": "GPL-3.0-or-later",
+  "author": "Abaxx Technologies <developer@abaxx.tech>",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/v-integration-react.umd.cjs",
+  "module": "./dist/v-integration-react.js",
+  "types": "./dist/v-integration-react.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/v-integration-react.d.ts",
+      "styles": "./dist/v-integration-react.css",
+      "import": "./dist/v-integration-react.js",
+      "require": "./dist/v-integration-react.umd.cjs"
+    },
+    "./index.css": {
+      "import": "./dist/v-integration-react.css",
+      "require": "./dist/v-integration-react.css"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "prebuild": "rm -rf dist",
+    "build": "tsc -b && vite build",
+    "dev:watch": "vite build --watch",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 <19",
+    "react-dom": ">=18.0.0 <19",
+    "uuid": ">=9.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.21.0",
+    "@tailwindcss/vite": "^4.0.9",
+    "@types/node": "^22.13.5",
+    "@types/react": "^18.0.10",
+    "@types/react-dom": "^18.0.4",
+    "@vitejs/plugin-react": "^4.3.4",
+    "eslint": "^9.21.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "globals": "^15.15.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tailwindcss": "^4.0.9",
+    "typescript": "~5.7.2",
+    "typescript-eslint": "^8.24.1",
+    "vite": "^6.2.0",
+    "vite-plugin-dts": "^4.5.3"
+  },
+  "dependencies": {
+    "react-qrcode-logo": "^3.0.0"
+  }
+}