@appboxo/web-sdk 1.0.6 → 1.0.7

package/README.md

@@ -40,14 +40,19 @@ const sdk = new AppboxoWebSDK({
   userId?: string;       // Optional, user reference identifier
   baseUrl?: string;      // Optional, default: "https://dashboard.appboxo.com/api/v1"
   debug?: boolean;        // Optional, default: false
-  onGetAuthCode?: () => Promise<string>; // Optional, for automatic auth code retrieval
+  onGetAuthCode?: () => Promise<string>; // Optional, for automatic auth code retrieval (OAuth)
+  onGetAuthTokens?: () => Promise<LoginResponse>; // Optional, for Boxo Connect Direct
   onPaymentRequest?: (params: PaymentRequest) => Promise<PaymentResponse>; // Optional, for handling payment requests
 });
 ```
 
 ### Authentication
 
-Two approaches:
+The SDK supports two authentication methods: **Boxo Connect OAuth** and **Boxo Connect Direct**.
+
+#### Boxo Connect OAuth
+
+Traditional OAuth 2.0 flow where the host app backend provides auth codes and access tokens to the Boxo Platform.
 
 **1. Set auth code explicitly**
 
@@ -68,11 +73,74 @@ const sdk = new AppboxoWebSDK({
 });
 ```
 
-The SDK will try these in order:
-
+The SDK will try OAuth methods in this order:
 1. Explicitly set auth code
-2. Callback function
-3. Mock auth code (fallback)
+2. Callback function (`onGetAuthCode`)
+3. Mock auth code (fallback for testing)
+
+#### Boxo Connect Direct
+
+Direct authentication flow where the host app backend calls Boxo Dashboard connect endpoint to get miniapp tokens, then provides them directly to the SDK.
+
+**1. Use `onAuth` lifecycle hook (Recommended)**
+
+```typescript
+const sdk = new AppboxoWebSDK({
+  clientId: "your-client-id",
+  appId: "your-app-id"
+});
+
+// onAuth hook is triggered when miniapp calls login()
+sdk.onAuth(async () => {
+  // Your backend calls Boxo Dashboard connect endpoint to get miniapp tokens
+  const response = await fetch('/api/get-miniapp-tokens', {
+    headers: { 'Authorization': `Bearer ${yourHostAppToken}` }
+  });
+  const tokens = await response.json();
+  
+  // Set tokens directly
+  sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);
+});
+```
+
+**2. Use `onGetAuthTokens` callback**
+
+```typescript
+const sdk = new AppboxoWebSDK({
+  clientId: "your-client-id",
+  appId: "your-app-id",
+  onGetAuthTokens: async () => {
+    const response = await fetch('/api/get-miniapp-tokens', {
+      headers: { 'Authorization': `Bearer ${yourHostAppToken}` }
+    });
+    const result = await response.json();
+    return {
+      token: result.access_token,
+      refresh_token: result.refresh_token
+    };
+  }
+});
+```
+
+**3. Pre-set tokens before login**
+
+```typescript
+const sdk = new AppboxoWebSDK({
+  clientId: "your-client-id",
+  appId: "your-app-id"
+});
+
+// If you already have tokens, set them before miniapp calls login()
+const tokens = await getTokensFromBackend();
+sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);
+```
+
+**Authentication Priority Order:**
+
+When the miniapp calls `login()`, the SDK will try these methods in order:
+1. Pre-set tokens (via `setAuthTokens()`)
+2. `onGetAuthTokens` callback
+3. OAuth flow (`setAuthCode()` or `onGetAuthCode` callback)
 
 ### Payment Processing
 
@@ -115,7 +183,9 @@ Note: When `onPaymentRequest` is set, the SDK automatically tells the miniapp it
 
 | Method | Description |
 |--------|-------------|
-| `setAuthCode(code)` | Set authentication code |
+| `setAuthCode(code)` | Set authentication code (OAuth) |
+| `setAuthTokens(token, refreshToken?)` | Set authentication tokens directly (Boxo Connect Direct) |
+| `onAuth(callback)` | Register lifecycle hook for authentication (Boxo Connect Direct) |
 | `mount(config)` | Create iframe and initialize SDK |
 | `setIframe(iframe)` | Set iframe element manually |
 | `initialize()` | Start listening for events |
@@ -165,7 +235,16 @@ function App() {
       },
     });
     
-    s.setAuthCode("your-auth-code");
+    // Boxo Connect OAuth
+    // s.setAuthCode("your-auth-code");
+    
+    // Boxo Connect Direct - onAuth hook
+    s.onAuth(async () => {
+      const response = await fetch('/api/get-miniapp-tokens');
+      const tokens = await response.json();
+      s.setAuthTokens(tokens.access_token, tokens.refresh_token);
+    });
+    
     s.onLoginComplete((success, data) => {
       console.log('Login:', success ? 'success' : 'failed', data);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appboxo/web-sdk",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Boxo Desktop Host App SDK for handling miniapp events",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",