@seaverse/data-service-sdk 0.3.0 → 0.5.0

package/README.md

@@ -41,18 +41,58 @@ These fields are enforced by Firestore Security Rules and ensure proper data iso
 npm install @seaverse/data-service-sdk
 ```
 
+## Browser vs Node.js Usage
+
+### For Build Tools (Webpack/Vite/Parcel)
+
+The SDK automatically uses the correct version:
+
+```javascript
+import { DataServiceClient } from '@seaverse/data-service-sdk';
+// Bundler will automatically use the browser version
+```
+
+### For Direct Browser Use (Without Build Tools)
+
+**Option 1: ES Module (Recommended)**
+
+```html
+<script type="module">
+  import { DataServiceClient } from 'https://unpkg.com/@seaverse/data-service-sdk/dist/browser.js';
+
+  const client = new DataServiceClient();
+  // Use the client...
+</script>
+```
+
+**Option 2: UMD via Script Tag**
+
+```html
+<script src="https://unpkg.com/@seaverse/data-service-sdk/dist/browser.umd.js"></script>
+<script>
+  const client = new SeaVerseDataService.DataServiceClient();
+  // Use the client...
+</script>
+```
+
+### For Node.js
+
+```javascript
+const { DataServiceClient } = require('@seaverse/data-service-sdk');
+// or
+import { DataServiceClient } from '@seaverse/data-service-sdk';
+```
+
 ## Quick Start
 
-### For Authenticated Users
+### 🚀 Easiest Way (Recommended - Auto Firebase Setup)
 
 ```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
 import { AuthClient } from '@seaverse/auth-sdk';
-import { initializeApp } from 'firebase/app';
-import { getAuth, signInWithCustomToken } from 'firebase/auth';
-import { getFirestore, collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
+import { collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
 
-// Step 1: Login user with Auth SDK
+// Step 1: Login user
 const authClient = new AuthClient({ appId: 'my-app-123' });
 const loginResponse = await authClient.loginWithEmail({
   email: 'user@example.com',
@@ -61,20 +101,15 @@ const loginResponse = await authClient.loginWithEmail({
 
 // Step 2: Get Firestore token
 const dataClient = new DataServiceClient();
-const firestoreToken = await dataClient.generateFirestoreToken({
-  token: loginResponse.token,  // JWT from auth
+const tokenResponse = await dataClient.generateFirestoreToken({
+  token: loginResponse.token,
   app_id: 'my-app-123'
 });
 
-// Step 3: Initialize Firebase
-const app = initializeApp({ projectId: firestoreToken.project_id });
-const auth = getAuth(app);
-await signInWithCustomToken(auth, firestoreToken.custom_token);
-const db = getFirestore(app);
+// Step 3: Auto-initialize Firebase (ONE LINE!)
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
-// Step 4: Use Firestore with proper paths
-const appId = firestoreToken.app_id;
-const userId = firestoreToken.user_id;
+// Step 4: Use Firestore directly!
 
 // Write to publicData (everyone can write)
 await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
@@ -101,31 +136,26 @@ await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
 });
 ```
 
-### For Guest Users
+### 👤 For Guest Users (Even Simpler!)
 
 ```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
-import { initializeApp } from 'firebase/app';
-import { getAuth, signInWithCustomToken } from 'firebase/auth';
-import { getFirestore, collection, addDoc, serverTimestamp } from 'firebase/firestore';
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
+import { collection, addDoc, serverTimestamp } from 'firebase/firestore';
 
 // Step 1: Get guest token (no authentication needed!)
 const dataClient = new DataServiceClient();
-const guestToken = await dataClient.generateGuestFirestoreToken({
+const tokenResponse = await dataClient.generateGuestFirestoreToken({
   app_id: 'my-app-123'
 });
 
-// Step 2: Initialize Firebase
-const app = initializeApp({ projectId: guestToken.project_id });
-const auth = getAuth(app);
-await signInWithCustomToken(auth, guestToken.custom_token);
-const db = getFirestore(app);
+// Step 2: Auto-initialize Firebase (ONE LINE!)
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
 
 // Step 3: Guest can write to publicData
-await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`), {
-  _appId: guestToken.app_id,
+await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
+  _appId: appId,
   _createdAt: serverTimestamp(),
-  _createdBy: guestToken.user_id,  // Guest user ID (e.g., 'guest-abc123')
+  _createdBy: userId,  // Guest user ID (e.g., 'guest-abc123')
   comment: 'Great app!',
   rating: 5
 });
@@ -133,6 +163,36 @@ await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`),
 // Note: Guests CANNOT access userData
 ```
 
+### 🔧 Manual Way (If you need more control)
+
+If you prefer to initialize Firebase manually:
+
+```typescript
+import { DataServiceClient, getFirebaseConfig } from '@seaverse/data-service-sdk';
+import { initializeApp } from 'firebase/app';
+import { getAuth, signInWithCustomToken } from 'firebase/auth';
+import { getFirestore } from 'firebase/firestore';
+
+const dataClient = new DataServiceClient();
+const tokenResponse = await dataClient.generateGuestFirestoreToken({
+  app_id: 'my-app-123'
+});
+
+// Option 1: Use getFirebaseConfig helper
+const firebaseConfig = getFirebaseConfig(tokenResponse);
+const app = initializeApp(firebaseConfig);
+
+// Option 2: Manual config
+const app = initializeApp({
+  apiKey: tokenResponse.web_api_key,  // ✅ Provided automatically!
+  projectId: tokenResponse.project_id
+});
+
+const auth = getAuth(app);
+await signInWithCustomToken(auth, tokenResponse.custom_token);
+const db = getFirestore(app);
+```
+
 ## API Reference
 
 ### DataServiceClient
@@ -190,11 +250,12 @@ interface GenerateFirestoreTokenRequest {
 ```typescript
 interface FirestoreTokenResponse {
   custom_token: string;     // Firebase Custom Token - use with signInWithCustomToken()
+  web_api_key: string;      // Firebase Web API Key - use with initializeApp()
   project_id: string;       // Firebase Project ID for initializeApp()
   database_id: string;      // Firestore Database ID
   app_id?: string;          // Application ID (use in Firestore paths)
   user_id: string;          // User ID (use in Firestore paths)
-  role?: string;            // User role ('guest', 'user', 'admin')
+  user_type: string;        // User type ('guest', 'user', 'admin', 'appadmin')
   expires_in: number;       // Token expiration in seconds (typically 3600)
 }
 ```
@@ -244,7 +305,63 @@ const guestToken = await client.generateGuestFirestoreToken({
 
 console.log('Guest Custom Token:', guestToken.custom_token);
 console.log('Guest User ID:', guestToken.user_id);
-console.log('Role:', guestToken.role); // 'guest'
+console.log('User Type:', guestToken.user_type); // 'guest'
+```
+
+### Helper Functions
+
+#### getFirebaseConfig
+
+Extract Firebase configuration from token response.
+
+```typescript
+getFirebaseConfig(tokenResponse: FirestoreTokenResponse): FirebaseConfig
+```
+
+**Example:**
+
+```typescript
+import { getFirebaseConfig } from '@seaverse/data-service-sdk';
+import { initializeApp } from 'firebase/app';
+
+const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
+const firebaseConfig = getFirebaseConfig(tokenResponse);
+// Returns: { apiKey: '...', projectId: '...' }
+
+const app = initializeApp(firebaseConfig);
+```
+
+#### initializeWithToken
+
+Automatically initialize Firebase and sign in with token (one-line setup).
+
+```typescript
+initializeWithToken(tokenResponse: FirestoreTokenResponse): Promise<{
+  app: FirebaseApp;
+  auth: Auth;
+  db: Firestore;
+  userId: string;
+  appId: string;
+}>
+```
+
+**Example:**
+
+```typescript
+import { initializeWithToken } from '@seaverse/data-service-sdk';
+
+const tokenResponse = await client.generateGuestFirestoreToken({ app_id: 'my-app' });
+
+// One line to get everything!
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
+
+// Ready to use Firestore
+await addDoc(collection(db, `appData/${appId}/publicData/posts`), { ... });
+```
+
+**Note:** This function requires Firebase SDK to be installed separately:
+```bash
+npm install firebase
 ```
 
 ## Common Use Cases
@@ -521,6 +638,55 @@ For issues and questions, please visit:
 - GitHub: https://github.com/seaverseai/sv-sdk
 - Email: support@seaverse.com
 
+## Browser Example (Vanilla JavaScript)
+
+Here's a complete example for using the SDK directly in the browser without any build tools:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>SeaVerse Data Service SDK - Browser Example</title>
+</head>
+<body>
+  <h1>Firestore Token Demo</h1>
+  <button id="getGuestToken">Get Guest Token</button>
+  <pre id="output"></pre>
+
+  <script type="module">
+    // Import from CDN
+    import { DataServiceClient } from 'https://unpkg.com/@seaverse/data-service-sdk/dist/browser.js';
+
+    const output = document.getElementById('output');
+    const client = new DataServiceClient();
+
+    document.getElementById('getGuestToken').addEventListener('click', async () => {
+      try {
+        output.textContent = 'Getting guest token...';
+
+        const guestToken = await client.generateGuestFirestoreToken({
+          app_id: 'my-app-123'
+        });
+
+        output.textContent = JSON.stringify({
+          custom_token: guestToken.custom_token.substring(0, 50) + '...',
+          user_id: guestToken.user_id,
+          role: guestToken.role,
+          project_id: guestToken.project_id,
+          expires_in: guestToken.expires_in
+        }, null, 2);
+
+        // Now you can use this token with Firebase SDK
+        console.log('Guest token received:', guestToken);
+      } catch (error) {
+        output.textContent = 'Error: ' + error.message;
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
 ## Related SDKs
 
 - [@seaverse/auth-sdk](../auth-sdk) - User authentication and account management