godgpt-web-auth 0.1.0

package/README.md

@@ -0,0 +1,203 @@
+# godgpt-web-auth
+
+A React authentication package with built-in support for **Google**, **Apple**, and **Email** sign-in.
+
+## Features
+
+- 🔐 **AuthProvider** - Context provider for managing auth state
+- 🎨 **LoginPage** - Pre-built, customizable login UI
+- 🪝 **useAuth** - Hook for accessing auth state and actions
+- 🔄 **Token Management** - Automatic token storage and refresh
+- 📦 **Zero Config** - Works out of the box with sensible defaults
+- 🔌 **Pluggable Storage** - Use localStorage, sessionStorage, or custom adapters
+
+## Installation
+
+```bash
+npm install godgpt-web-auth
+# or
+yarn add godgpt-web-auth
+# or
+pnpm add godgpt-web-auth
+```
+
+## Quick Start
+
+### 1. Wrap your app with AuthProvider
+
+```tsx
+import { AuthProvider, LoginPage, useAuth } from "godgpt-web-auth";
+import type { AuthConfig } from "godgpt-web-auth";
+
+const authConfig: AuthConfig = {
+  backendUrl: process.env.NEXT_PUBLIC_AUTH_BACKEND_URL,
+  appId: "your-app-id",
+  google: {
+    clientId: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID,
+  },
+  apple: {
+    clientId: process.env.NEXT_PUBLIC_APPLE_CLIENT_ID, // Service ID for web
+    redirectUri: "https://your-domain.com",
+  },
+  email: {
+    enabled: true,
+  },
+};
+
+function App() {
+  return (
+    <AuthProvider
+      config={authConfig}
+      onLogout={() => {
+        // Handle logout (e.g., redirect to home)
+        window.location.href = "/";
+      }}
+    >
+      <AppContent />
+    </AuthProvider>
+  );
+}
+```
+
+### 2. Use the LoginPage component
+
+```tsx
+function AppContent() {
+  const { tokens, logout, isLoading, isAuthLoaded } = useAuth();
+
+  // Show loading while checking stored tokens
+  if (!isAuthLoaded) {
+    return <div>Loading...</div>;
+  }
+
+  // Show login page if not authenticated
+  if (!tokens) {
+    return <LoginPage />;
+  }
+
+  // User is authenticated
+  return (
+    <div>
+      <h1>Welcome!</h1>
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+## Exports
+
+### Main Exports
+
+| Export         | Type      | Description                                                        |
+| -------------- | --------- | ------------------------------------------------------------------ |
+| `AuthProvider` | Component | Context provider - wrap your app with this                         |
+| `LoginPage`    | Component | Pre-built login UI with all providers                              |
+| `useAuth`      | Hook      | Access auth state: `tokens`, `logout`, `isLoading`, `isAuthLoaded` |
+
+### Types
+
+| Type               | Description                           |
+| ------------------ | ------------------------------------- |
+| `AuthConfig`       | Configuration object for AuthProvider |
+| `AuthContextValue` | Return type of useAuth hook           |
+| `JWTData`          | Token data structure                  |
+| `AuthResult`       | Result from sign-in attempts          |
+| `AuthProviderType` | `"google" \| "apple" \| "password"`   |
+
+### Advanced Exports
+
+For custom implementations:
+
+```tsx
+// Individual sign-in strategies
+import {
+  signInWithEmail,
+  signInWithGoogle,
+  signInWithApple,
+} from "godgpt-web-auth";
+
+// Storage adapters
+import {
+  storageService,
+  createStorageService,
+  localStorageAdapter,
+  memoryStorageAdapter,
+} from "godgpt-web-auth";
+
+// Token services
+import { exchangeToken, refreshToken } from "godgpt-web-auth";
+```
+
+## Configuration
+
+### AuthConfig
+
+```tsx
+interface AuthConfig {
+  /** Backend URL for token exchange */
+  backendUrl: string;
+
+  /** App identifier sent with token requests */
+  appId?: string;
+
+  /** Google OAuth configuration */
+  google?: {
+    clientId: string;
+  };
+
+  /** Apple Sign In configuration */
+  apple?: {
+    clientId: string; // Service ID (not App ID) for web
+    redirectUri?: string; // Required for production (HTTPS)
+  };
+
+  /** Email/password configuration */
+  email?: {
+    enabled: boolean;
+  };
+}
+```
+
+## useAuth Hook
+
+```tsx
+const {
+  tokens, // JWTData | null - Current tokens
+  logout, // () => Promise<void> - Clear tokens and call onLogout
+  isLoading, // boolean - Sign-in in progress
+  isAuthLoaded, // boolean - Initial token check complete
+} = useAuth();
+```
+
+## OAuth Provider Setup
+
+### Google
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+2. Create OAuth 2.0 Client ID (Web application)
+3. Add your domain to **Authorized JavaScript origins**
+4. Add your domain to **Authorized redirect URIs**
+
+### Apple
+
+1. Go to [Apple Developer Portal](https://developer.apple.com/account/resources/identifiers/list/serviceId)
+2. Create a **Service ID** (not App ID) for web
+3. Enable "Sign In with Apple"
+4. Configure domains and return URLs
+5. **Note**: Apple requires HTTPS for redirect URIs
+
+## Token Storage
+
+By default, tokens are stored in `localStorage`. For custom storage:
+
+```tsx
+import { createStorageService, memoryStorageAdapter } from "godgpt-web-auth";
+
+// Use memory storage (for SSR or testing)
+const customStorage = createStorageService(memoryStorageAdapter);
+```
+
+## License
+
+MIT