@autogames/sdk 1.1.1

package/README.md

@@ -0,0 +1,732 @@
+# AutoGames SDK
+
+A TypeScript SDK for web-based games with Privy authentication and AutoGames backend integration. This SDK provides a simple interface for Unity web games to interact with Privy's authentication system and the AutoGames platform without directly dealing with React.
+
+## Quick Start (Development)
+
+```bash
+# Clone and install
+git clone <repo-url>
+cd autogames-sdk
+pnpm install
+
+# Build the SDK
+pnpm build
+
+# Run the example app
+pnpm dev
+```
+
+Open `http://localhost:3000` to test the SDK in the example app!
+
+## Features
+
+- 🔐 **Privy Authentication** - Seamless social login and wallet authentication
+- 🎮 **Unity-Friendly** - Simple JavaScript API accessible from Unity WebGL
+- 📦 **Single Bundle** - Distributed as a single JS file with bundled Privy App ID
+- 🔧 **Build-Time Configuration** - Configure Privy App ID and API base URL via environment variables
+- 🔄 **Auto Token Refresh** - Automatic JWT token refresh with Web Locks API coordination across tabs
+- 💼 **TypeScript Support** - Full type definitions using Privy's native types
+- 🎨 **Flexible Configuration** - Customize UI, login methods, wallets, and more
+- 🔒 **Type-Safe** - Uses Privy's `PrivyClientConfig` types directly for perfect compatibility
+- 🌐 **Backend Integration** - Seamless integration with AutoGames backend API
+
+This SDK is designed specifically for the AutoGames ecosystem:
+
+- **Agent-Based Authentication** - Each game requires an `agentId` for proper backend integration
+- **Consistent Experience** - Unified authentication flow across all games
+- **Easy Customization** - Match the UI to your game's branding with simple config options
+- **Full Privy Power** - Access to all Privy features (embedded wallets, MFA, social logins, etc.)
+- **Backend Token Exchange** - Automatic token exchange from Privy tokens to AutoGames JWT tokens
+
+## Installation
+
+### Via CDN (Recommended for Unity)
+
+Add the SDK to your `index.html`:
+
+```html
+<script src="https://unpkg.com/autogames-sdk@latest/dist/autogames-sdk.js"></script>
+<script>
+  // SDK is available as window.AutoGamesSDK
+  // Initialize with your agentId (required)
+  window.AutoGamesSDK.init({
+    agentId: 1 // Your game's agent ID from AutoGames platform
+  });
+</script>
+```
+
+### Via npm
+
+```bash
+npm install autogames-sdk
+# or
+pnpm add autogames-sdk
+# or
+yarn add autogames-sdk
+```
+
+```javascript
+import { AutoGamesSDK } from 'autogames-sdk';
+// Optional: Import Privy types for advanced configuration
+import type { PrivyClientConfig } from 'autogames-sdk';
+
+// Initialize with agentId (required)
+await AutoGamesSDK.init({
+  agentId: 1 // Your game's agent ID from AutoGames platform
+});
+
+// Or with custom appearance
+await AutoGamesSDK.init({
+  agentId: 1,
+  appearance: {
+    theme: 'dark',
+    accentColor: '#FF6B6B'
+  }
+});
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+**Required: Agent ID**
+
+The SDK requires an `agentId` parameter, which identifies your game in the AutoGames platform. This is used for backend token exchange and user management.
+
+```javascript
+// Initialize with agentId (required)
+await window.AutoGamesSDK.init({
+  agentId: 1, // Your game's agent ID from AutoGames platform
+});
+```
+
+**With customization:**
+
+```javascript
+// Customize appearance to match your game's branding
+await window.AutoGamesSDK.init({
+  agentId: 1, // Required: Your game's agent ID
+  appearance: {
+    theme: 'dark',
+    accentColor: '#FF6B6B',
+    logo: 'https://yourgame.com/logo.png'
+  },
+  onAuthStateChange: (user) => {
+    console.log('Auth state changed:', user);
+  }
+});
+```
+
+### 2. Trigger Login
+
+```javascript
+try {
+  await window.AutoGamesSDK.login();
+  // Note: With OAuth providers (e.g., Google), the page may reload during authentication.
+  // Use the onAuthStateChange callback in init() or poll isAuthenticated() to detect completion.
+} catch (error) {
+  console.error('Login failed:', error);
+}
+```
+
+### 3. Get User Profile
+
+**Get cached profile (synchronous):**
+
+```javascript
+const profile = window.AutoGamesSDK.getProfile();
+if (profile) {
+  console.log('User:', profile.Email, profile.ID);
+  console.log('Balance:', profile.BalanceUSD);
+  console.log('Ethereum Address:', profile.EthereumAddress);
+}
+```
+
+**Fetch fresh profile from backend (asynchronous):**
+
+```javascript
+const profile = await window.AutoGamesSDK.fetchProfile();
+if (profile) {
+  console.log('Fresh user data:', profile);
+}
+```
+
+### 4. Logout
+
+```javascript
+await window.AutoGamesSDK.logout();
+// This will logout from both Privy and AutoGames backend
+```
+
+## API Reference
+
+### `init(config: SDKConfig): Promise<void>`
+
+Initialize the SDK with required configuration. The SDK requires an `agentId` to identify your game in the AutoGames platform.
+
+**Parameters:**
+- `config`: SDK configuration object
+  - `agentId` (required): Your game's agent ID from the AutoGames platform. Used for backend token exchange and user management.
+  - `privyAppId` (optional): Custom Privy App ID. Defaults to bundled AutoGames app ID.
+  - `appearance` (optional): Customize the Privy UI appearance (uses Privy's native `PrivyClientConfig['appearance']`)
+    - `theme`: `'light'`, `'dark'`, or custom hex color (default: `'light'`)
+    - `accentColor`: Hex color code (default: `'#676FFF'`)
+    - `logo`: URL to your game's logo or React element
+    - `landingHeader`: Header text for the login modal
+    - `loginMessage`: Subtitle text for the login modal
+    - `showWalletLoginFirst`: Show wallet options first (default: `false`)
+    - `walletChainType`: `'ethereum-only'`, `'solana-only'`, or `'ethereum-and-solana'`
+    - `walletList`: Array of wallet providers to show
+  - `loginMethods` (optional): Array of enabled login methods (uses Privy's native `PrivyClientConfig['loginMethods']`)
+    - Available methods: `'email'`, `'sms'`, `'wallet'`, `'google'`, `'twitter'`, `'discord'`, `'github'`, `'linkedin'`, `'spotify'`, `'instagram'`, `'tiktok'`, `'apple'`, `'farcaster'`, `'telegram'`, `'passkey'`
+  - `loginMethodsAndOrder` (optional): Advanced login methods configuration with custom ordering (uses Privy's native `PrivyClientConfig['loginMethodsAndOrder']`)
+  - `config` (optional): Any additional Privy configuration options (embedded wallets, MFA, external wallets, etc.)
+  - `onAuthStateChange` (optional): Callback fired when authentication state changes
+
+> **Note:** The SDK uses Privy's native types directly, so you get full type safety and access to all Privy configuration options. See [Privy's documentation](https://docs.privy.io/reference/react-auth/modules#privyclientconfig) for complete configuration details.
+
+**Examples:**
+
+Basic initialization:
+```javascript
+// Required: agentId identifies your game in AutoGames platform
+await AutoGamesSDK.init({
+  agentId: 1
+});
+```
+
+Custom branding:
+```javascript
+await AutoGamesSDK.init({
+  agentId: 1, // Required
+  appearance: {
+    theme: 'dark',
+    accentColor: '#FF6B6B',
+    logo: 'https://yourgame.com/logo.png'
+  },
+  onAuthStateChange: (user) => {
+    if (user) {
+      console.log('User logged in:', user.Email);
+    } else {
+      console.log('User logged out');
+    }
+  }
+});
+```
+
+Customize login methods:
+```javascript
+await AutoGamesSDK.init({
+  agentId: 1,
+  loginMethods: ['email', 'wallet', 'google']  // Only these methods will be available
+});
+```
+
+Wallet-first experience:
+```javascript
+await AutoGamesSDK.init({
+  agentId: 1,
+  appearance: {
+    showWalletLoginFirst: true,
+    walletChainType: 'ethereum-only',
+    landingHeader: 'Connect Your Wallet',
+    loginMessage: 'Sign in with your crypto wallet'
+  }
+});
+```
+
+Advanced configuration with embedded wallets:
+```javascript
+await AutoGamesSDK.init({
+  agentId: 1,
+  appearance: {
+    theme: 'dark',
+    accentColor: '#FF6B6B'
+  },
+  config: {
+    // Enable embedded wallet creation on login
+    embeddedWallets: {
+      createOnLogin: 'users-without-wallets',
+      showWalletUIs: true
+    },
+    // Enable MFA
+    mfa: {
+      noPromptOnMfaRequired: false
+    }
+  }
+});
+```
+
+### `login(): Promise<void>`
+
+Trigger the Privy login flow. The SDK handles token exchange with the AutoGames backend automatically.
+
+**Returns:** `Promise<void>`
+
+**Note:** With OAuth providers (e.g., Google), the page may reload during authentication. Use the `onAuthStateChange` callback in `init()` or poll `isAuthenticated()`/`getProfile()` to detect when login completes.
+
+**Example:**
+```javascript
+try {
+  await AutoGamesSDK.login();
+  // Login flow initiated. Use onAuthStateChange callback to detect completion.
+} catch (error) {
+  console.error('Login failed:', error);
+}
+```
+
+### `logout(): Promise<void>`
+
+Log out the current user.
+
+**Example:**
+```javascript
+await AutoGamesSDK.logout();
+```
+
+### `getProfile(): User | null`
+
+Get the current user's profile synchronously (cached from last fetch).
+
+**Returns:** `User | null`
+
+**Example:**
+```javascript
+const profile = AutoGamesSDK.getProfile();
+if (profile) {
+  console.log('User ID:', profile.ID);
+  console.log('Email:', profile.Email);
+  console.log('Balance:', profile.BalanceUSD);
+}
+```
+
+### `fetchProfile(): Promise<User | null>`
+
+Fetch a fresh user profile from the AutoGames backend and update the cache.
+
+**Returns:** `Promise<User | null>`
+
+**Example:**
+```javascript
+const profile = await AutoGamesSDK.fetchProfile();
+if (profile) {
+  console.log('Fresh user data:', profile);
+}
+```
+
+### `isAuthenticated(): boolean`
+
+Check if a user is currently authenticated.
+
+**Returns:** `boolean`
+
+### `isReady(): boolean`
+
+Check if the SDK is ready to use.
+
+**Returns:** `boolean`
+
+### `getAuthState(): AuthState`
+
+Get the complete authentication state.
+
+**Returns:** `AuthState`
+
+```typescript
+interface AuthState {
+  isAuthenticated: boolean;
+  isReady: boolean;
+  user: User | null;
+}
+```
+
+### `destroy(): void`
+
+Clean up SDK subscriptions and reset state. Useful for testing or when unmounting the SDK.
+
+**Example:**
+```javascript
+AutoGamesSDK.destroy();
+```
+
+## Types
+
+### User
+
+The user profile returned by the SDK includes information from the AutoGames backend:
+
+```typescript
+interface User {
+  // Base entity fields
+  ID: number;
+  CreatedAt: string;
+  UpdatedAt: string;
+  
+  // User profile fields
+  BalanceUSD: number;
+  Email: string;
+  GeoInfo: string;
+  ImageThumbnailURL: string;
+  ImageURL: string;
+  IsEmailVerified: boolean;
+  Name: string;
+  PrivyUserID: string;
+  WalletPublicKey: string;
+  EthereumAddress: string;
+  SolanaAddress: string;
+  SolanaBalanceLamports: number;
+}
+```
+
+### SDKConfig
+
+```typescript
+import type { PrivyClientConfig } from '@privy-io/react-auth';
+import type { User } from 'autogames-sdk';
+
+interface SDKConfig {
+  /**
+   * Required: Agent ID. Game ID in the AutoGames platform.
+   * Used for backend token exchange and user management.
+   */
+  agentId: number;
+  
+  /**
+   * Optional: Privy App ID. If not provided, uses the bundled default.
+   * Only needed if you want to use a different Privy app for isolated user base.
+   */
+  privyAppId?: string;
+  
+  /**
+   * Optional: Customize the appearance of Privy UI elements.
+   * Uses Privy's native appearance configuration.
+   */
+  appearance?: PrivyClientConfig['appearance'];
+  
+  /**
+   * Optional: Configure which login methods are available.
+   * Uses Privy's native login methods configuration.
+   */
+  loginMethods?: PrivyClientConfig['loginMethods'];
+  
+  /**
+   * Optional: Advanced login methods configuration with ordering.
+   */
+  loginMethodsAndOrder?: PrivyClientConfig['loginMethodsAndOrder'];
+  
+  /**
+   * Optional: Additional Privy client configuration options.
+   * Supports embedded wallets, MFA, external wallets, etc.
+   */
+  config?: Omit<PrivyClientConfig, 'appearance' | 'loginMethods' | 'loginMethodsAndOrder'>;
+  
+  /**
+   * Optional: Callback fired when authentication state changes
+   */
+  onAuthStateChange?: (user: User | null) => void;
+}
+```
+
+> **Type Safety:** The SDK uses Privy's native `PrivyClientConfig` types directly, giving you full IntelliSense support and type checking for all Privy configuration options. See [Privy's documentation](https://docs.privy.io/reference/react-auth/modules#privyclientconfig) for complete details.
+
+## Unity Integration
+
+### C# Example
+
+```csharp
+using UnityEngine;
+using System.Runtime.InteropServices;
+
+public class AutoGamesAuth : MonoBehaviour
+{
+    [DllImport("__Internal")]
+    private static extern void InitSDK(int agentId);
+    
+    [DllImport("__Internal")]
+    private static extern void Login();
+    
+    [DllImport("__Internal")]
+    private static extern void Logout();
+    
+    [DllImport("__Internal")]
+    private static extern string GetUserProfile();
+    
+    [DllImport("__Internal")]
+    private static extern bool IsAuthenticated();
+    
+    public int agentId = 1; // Set your agent ID in Unity Inspector
+    
+    void Start()
+    {
+        #if UNITY_WEBGL && !UNITY_EDITOR
+        InitSDK(agentId); // Initialize with your agent ID
+        #endif
+    }
+    
+    public void OnLoginButtonClick()
+    {
+        #if UNITY_WEBGL && !UNITY_EDITOR
+        Login();
+        #endif
+    }
+    
+    public void OnLogoutButtonClick()
+    {
+        #if UNITY_WEBGL && !UNITY_EDITOR
+        Logout();
+        #endif
+    }
+    
+    public void OnCheckAuthButtonClick()
+    {
+        #if UNITY_WEBGL && !UNITY_EDITOR
+        bool isAuth = IsAuthenticated();
+        Debug.Log($"Is Authenticated: {isAuth}");
+        #endif
+    }
+}
+```
+
+### JavaScript Plugin (Assets/Plugins/WebGL/AutoGames.jslib)
+
+```javascript
+mergeInto(LibraryManager.library, {
+    InitSDK: function(agentId) {
+        window.AutoGamesSDK.init({
+            agentId: agentId,
+            onAuthStateChange: function(user) {
+                if (user) {
+                    SendMessage('AutoGamesAuth', 'OnAuthStateChanged', JSON.stringify(user));
+                } else {
+                    SendMessage('AutoGamesAuth', 'OnAuthStateChanged', '');
+                }
+            }
+        });
+    },
+    
+    Login: function() {
+        window.AutoGamesSDK.login()
+            .then(function() {
+                SendMessage('AutoGamesAuth', 'OnLoginInitiated', '');
+            })
+            .catch(function(error) {
+                SendMessage('AutoGamesAuth', 'OnLoginError', error.message);
+            });
+    },
+    
+    Logout: function() {
+        window.AutoGamesSDK.logout()
+            .then(function() {
+                SendMessage('AutoGamesAuth', 'OnLogoutSuccess', '');
+            })
+            .catch(function(error) {
+                SendMessage('AutoGamesAuth', 'OnLogoutError', error.message);
+            });
+    },
+    
+    GetUserProfile: function() {
+        var profile = window.AutoGamesSDK.getProfile();
+        if (profile) {
+            var json = JSON.stringify(profile);
+            var buffer = _malloc(lengthBytesUTF8(json) + 1);
+            stringToUTF8(json, buffer, lengthBytesUTF8(json) + 1);
+            return buffer;
+        }
+        return null;
+    },
+    
+    IsAuthenticated: function() {
+        return window.AutoGamesSDK.isAuthenticated() ? 1 : 0;
+    }
+});
+```
+
+## Architecture
+
+The SDK uses a **domain-driven design** architecture with a bridge pattern to connect Privy's React SDK with vanilla JavaScript:
+
+### Domain Structure
+
+```
+packages/sdk/src/
+├── domains/
+│   ├── auth/              # Authentication domain
+│   │   ├── api/          # Backend API calls
+│   │   │   ├── exchange-privy-token.ts  # Exchange Privy token for JWT
+│   │   │   └── logout.ts                # Backend logout
+│   │   └── stores/
+│   │       └── auth-store.ts            # Zustand auth state store
+│   └── user/              # User domain
+│       ├── api/
+│       │   └── get-user.ts              # Fetch user from backend
+│       └── types/
+│           └── index.ts                 # User type definitions
+├── shared/
+│   ├── components/
+│   │   └── privy-bridge.tsx            # React bridge component
+│   ├── lib/
+│   │   └── axios.ts                    # Axios instance with token refresh
+│   └── types/
+│       └── index.ts                    # Shared type definitions
+├── bridge-mount.tsx                    # Bridge mounting logic
+├── sdk.ts                              # Main SDK class
+└── main.tsx                            # Entry point and exports
+```
+
+### How It Works
+
+1. **Bridge Pattern**: A hidden React component (`PrivyBridge`) mounts in the background to use Privy's React hooks
+2. **State Management**: Zustand store (`authStore`) manages authentication state and syncs with Privy
+3. **Token Exchange**: On login, Privy token is exchanged for AutoGames JWT token via backend API
+4. **Token Refresh**: Axios interceptor automatically refreshes JWT tokens using httpOnly cookies
+5. **Web Locks API**: Token refresh is coordinated across browser tabs using Web Locks API
+6. **Public API**: The SDK class (`AutoGamesSDK`) exposes a simple, promise-based API
+
+### Backend Integration
+
+The SDK integrates with the AutoGames backend:
+
+- **Token Exchange**: `/sso/exchange-privy-token` - Exchanges Privy token for JWT token
+- **Token Refresh**: `/sso/refresh-token` - Refreshes JWT token using httpOnly cookie
+- **Logout**: `/sso/logout` - Logs out from backend
+- **User API**: `/users/:id` - Fetches user profile
+
+All API calls include:
+- `Authorization: Bearer <access_token>` header
+- `X-Auth-Type: jwt` header
+- Automatic token refresh on 401 errors
+
+## Repository Structure
+
+This is a **pnpm workspace monorepo** containing:
+
+```
+autogames-sdk/
+├── packages/
+│   ├── sdk/                    # Main SDK package (autogames-sdk)
+│   │   ├── src/
+│   │   │   ├── domains/        # Domain-driven architecture
+│   │   │   ├── shared/         # Shared components and utilities
+│   │   │   ├── bridge-mount.tsx
+│   │   │   ├── sdk.ts          # Main SDK class
+│   │   │   └── main.tsx        # Entry point
+│   │   ├── dist/               # Built SDK bundles
+│   │   └── package.json
+│   └── example/                # Example React app for testing
+│       ├── src/
+│       │   ├── demos/          # Demo components
+│       │   └── App.tsx
+│       └── package.json
+├── pnpm-workspace.yaml
+├── package.json                # Root workspace config
+└── README.md
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies for all packages
+pnpm install
+
+# Build the SDK
+pnpm build
+
+# Or build all packages
+pnpm build:all
+```
+
+### Running the Example App
+
+The example app is a React application that demonstrates SDK integration:
+
+```bash
+# Start the example app (automatically uses local SDK)
+pnpm dev
+
+# Or run from the example package directory
+cd packages/example
+pnpm dev
+```
+
+The example app will be available at `http://localhost:3000` and includes:
+- **Login & Methods Tab**: Test authentication flow and SDK methods
+- **SDK State Tab**: Real-time view of authentication state
+- **Configuration Tab**: Test different SDK configurations
+
+### Building the SDK
+
+```bash
+# Build SDK package
+pnpm --filter autogames-sdk build
+
+# Or from the SDK directory
+cd packages/sdk
+pnpm build
+```
+
+The Privy App ID and API base URL can be configured at build time via environment variables:
+
+```bash
+# Using environment variables
+VITE_PRIVY_APP_ID=your-app-id VITE_API_BASE_URL=https://api.autogames.com pnpm build
+
+# Or create a .env file in packages/sdk/
+cd packages/sdk
+cat > .env << EOF
+VITE_PRIVY_APP_ID=cmh3ikmhm00o6gz0d46f40swl
+VITE_API_BASE_URL=https://api.autogames.com
+EOF
+pnpm build
+```
+
+**Example `.env` file:**
+```env
+# Privy App ID for AutoGames SDK
+# This will be bundled into the SDK at build time
+VITE_PRIVY_APP_ID=cmh3ikmhm00o6gz0d46f40swl
+
+# AutoGames API base URL
+# Used for token exchange, user fetching, and other backend operations
+VITE_API_BASE_URL=https://api.autogames.com
+```
+
+### Development Workflow
+
+1. **Make changes to SDK** (`packages/sdk/src/`)
+2. **Rebuild SDK**: `pnpm --filter autogames-sdk build`
+3. **Test in example app**: The example app uses `workspace:*` so it automatically uses your local build
+4. **Run example app**: `pnpm dev` to see changes
+
+### Workspace Commands
+
+```bash
+# Run command in specific package
+pnpm --filter autogames-sdk <command>
+pnpm --filter example <command>
+
+# Run command in all packages
+pnpm -r <command>
+
+# Check code quality
+pnpm check
+```
+
+## Authentication Flow
+
+1. **Initialization**: SDK mounts a hidden React bridge component that initializes Privy
+2. **Login**: User authenticates with Privy (social login, wallet, etc.)
+3. **Token Exchange**: SDK automatically exchanges Privy token for AutoGames JWT token
+4. **State Sync**: User profile is fetched and stored in Zustand store
+5. **Token Refresh**: Axios interceptor automatically refreshes expired tokens
+6. **Logout**: Clears both Privy and AutoGames backend sessions
+
+### Token Management
+
+- **Access Token**: JWT token stored in memory (Zustand store)
+- **Refresh Token**: Stored in httpOnly cookie (secure, not accessible to JavaScript)
+- **Automatic Refresh**: Tokens are refreshed automatically before expiration
+- **Cross-Tab Coordination**: Web Locks API ensures only one tab refreshes tokens at a time
+