@seaverse/data-service-sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,39 @@
 # @seaverse/data-service-sdk
 
-SeaVerse Data Service SDK for managing Firestore tokens in frontend applications.
+SeaVerse Data Service SDK for accessing Firestore with secure token management and three-tier permission model.
 
 ## Features
 
-- Generate Firestore tokens for authenticated users
-- Generate Firestore tokens for guest users
-- TypeScript support with full type definitions
-- Promise-based API using axios
-- Automatic response unwrapping
+- 🔐 Secure Firestore token generation for authenticated users and guests
+- 🎯 Three-tier permission model (publicRead, publicData, userData)
+- 🚀 Direct Firestore access - no proxy server needed
+- 🔒 Automatic data isolation by app_id
+- 📝 TypeScript support with full type definitions
+- 🤖 LLM-friendly documentation with clear examples
+
+## Three-Tier Permission Model
+
+SeaVerse organizes your Firestore data into three permission levels:
+
+| Permission Level | Path Pattern | Read Access | Write Access | Use Case |
+|-----------------|--------------|-------------|--------------|----------|
+| **publicRead** | `appData/{app_id}/publicRead/...` | All authenticated users | Admin only | System configs, announcements, static content |
+| **publicData** | `appData/{app_id}/publicData/...` | All authenticated users | All authenticated users | User posts, comments, shared content |
+| **userData** | `appData/{app_id}/userData/{user_id}/...` | Owner only | Owner only | User settings, private notes, personal data |
+
+### Required Fields
+
+All Firestore documents MUST include these three fields:
+
+```typescript
+{
+  _appId: string,        // Your application ID (for data isolation)
+  _createdAt: timestamp, // Server timestamp (use serverTimestamp())
+  _createdBy: string     // User ID who created the document
+}
+```
+
+These fields are enforced by Firestore Security Rules and ensure proper data isolation.
 
 ## Installation
 
@@ -18,29 +43,101 @@ npm install @seaverse/data-service-sdk
 
 ## Quick Start
 
+### For Authenticated Users
+
 ```typescript
 import { DataServiceClient } 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';
+
+// Step 1: Login user with Auth SDK
+const authClient = new AuthClient({ appId: 'my-app-123' });
+const loginResponse = await authClient.loginWithEmail({
+  email: 'user@example.com',
+  password: 'password123'
+});
 
-// Create client instance
-const client = new DataServiceClient();
+// Step 2: Get Firestore token
+const dataClient = new DataServiceClient();
+const firestoreToken = await dataClient.generateFirestoreToken({
+  token: loginResponse.token,  // JWT from auth
+  app_id: 'my-app-123'
+});
 
-// For authenticated users
-const token = await client.generateFirestoreToken({
-  token: 'user-jwt-token',
-  app_id: 'your-app-id',
+// 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 4: Use Firestore with proper paths
+const appId = firestoreToken.app_id;
+const userId = firestoreToken.user_id;
+
+// Write to publicData (everyone can write)
+await addDoc(collection(db, `appData/${appId}/publicData/posts`), {
+  _appId: appId,              // REQUIRED
+  _createdAt: serverTimestamp(), // REQUIRED
+  _createdBy: userId,         // REQUIRED
+  title: 'My First Post',
+  content: 'Hello world!'
 });
 
-// For guest users
-const guestToken = await client.generateGuestFirestoreToken({
-  app_id: 'your-app-id',
+// Read from publicData
+const snapshot = await getDocs(collection(db, `appData/${appId}/publicData/posts`));
+snapshot.forEach(doc => {
+  console.log(doc.id, doc.data());
+});
+
+// Write to userData (private)
+await addDoc(collection(db, `appData/${appId}/userData/${userId}/notes`), {
+  _appId: appId,              // REQUIRED
+  _createdAt: serverTimestamp(), // REQUIRED
+  _createdBy: userId,         // REQUIRED
+  title: 'Private Note',
+  content: 'Only I can see this'
+});
+```
+
+### For Guest Users
+
+```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';
+
+// Step 1: Get guest token (no authentication needed!)
+const dataClient = new DataServiceClient();
+const guestToken = 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 3: Guest can write to publicData
+await addDoc(collection(db, `appData/${guestToken.app_id}/publicData/comments`), {
+  _appId: guestToken.app_id,
+  _createdAt: serverTimestamp(),
+  _createdBy: guestToken.user_id,  // Guest user ID (e.g., 'guest-abc123')
+  comment: 'Great app!',
+  rating: 5
 });
+
+// Note: Guests CANNOT access userData
 ```
 
 ## API Reference
 
 ### DataServiceClient
 
-The main client for interacting with the Data Service API.
+The main client for generating Firestore tokens.
 
 #### Constructor
 
@@ -61,8 +158,8 @@ const client = new DataServiceClient({
   baseURL: 'https://auth.seaverse.ai',
   timeout: 15000,
   headers: {
-    'X-Custom-Header': 'value',
-  },
+    'X-Custom-Header': 'value'
+  }
 });
 ```
 
@@ -83,7 +180,7 @@ generateFirestoreToken(
 
 ```typescript
 interface GenerateFirestoreTokenRequest {
-  token: string;    // User's JWT token
+  token: string;    // User's JWT token from Auth SDK
   app_id: string;   // Application ID
 }
 ```
@@ -92,32 +189,27 @@ interface GenerateFirestoreTokenRequest {
 
 ```typescript
 interface FirestoreTokenResponse {
-  id_token: string;         // Firebase ID Token
-  refresh_token?: string;   // Firebase Refresh Token (optional)
-  project_id: string;       // Firebase Project ID
+  custom_token: string;     // Firebase Custom Token - use with signInWithCustomToken()
+  project_id: string;       // Firebase Project ID for initializeApp()
   database_id: string;      // Firestore Database ID
-  app_id?: string;          // Application ID
-  user_id: string;          // User ID
-  role?: string;            // User role
-  expires_in: number;       // Expiration time in seconds (typically 3600)
+  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')
+  expires_in: number;       // Token expiration in seconds (typically 3600)
 }
 ```
 
 **Example:**
 
 ```typescript
-try {
-  const response = await client.generateFirestoreToken({
-    token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
-    app_id: 'my-app',
-  });
+const firestoreToken = await client.generateFirestoreToken({
+  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+  app_id: 'my-app-123'
+});
 
-  console.log('Firestore ID Token:', response.id_token);
-  console.log('User ID:', response.user_id);
-  console.log('Expires in:', response.expires_in, 'seconds');
-} catch (error) {
-  console.error('Failed to generate Firestore token:', error);
-}
+console.log('Custom Token:', firestoreToken.custom_token);
+console.log('User ID:', firestoreToken.user_id);
+console.log('App ID:', firestoreToken.app_id);
 ```
 
 #### generateGuestFirestoreToken
@@ -141,126 +233,141 @@ interface GenerateGuestFirestoreTokenRequest {
 
 **Response:**
 
-Same as `FirestoreTokenResponse` above, with `role` typically set to `'guest'`.
+Same as `FirestoreTokenResponse` above, with `role` set to `'guest'`.
 
 **Example:**
 
 ```typescript
-try {
-  const response = await client.generateGuestFirestoreToken({
-    app_id: 'my-app',
-  });
+const guestToken = await client.generateGuestFirestoreToken({
+  app_id: 'my-app-123'
+});
 
-  console.log('Guest Firestore ID Token:', response.id_token);
-  console.log('Guest User ID:', response.user_id);
-  console.log('Role:', response.role); // 'guest'
-} catch (error) {
-  console.error('Failed to generate guest Firestore token:', error);
-}
+console.log('Guest Custom Token:', guestToken.custom_token);
+console.log('Guest User ID:', guestToken.user_id);
+console.log('Role:', guestToken.role); // 'guest'
 ```
 
-## Usage Examples
+## Common Use Cases
 
-### Browser Environment
+### Use Case 1: Public Forum with Comments
 
 ```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
+// Anyone (including guests) can post comments
+await addDoc(collection(db, `appData/${appId}/publicData/comments`), {
+  _appId: appId,
+  _createdAt: serverTimestamp(),
+  _createdBy: userId,
+  postId: 'post-123',
+  comment: 'Great post!',
+  likes: 0
+});
 
-const client = new DataServiceClient();
+// Anyone can read comments
+const comments = await getDocs(
+  collection(db, `appData/${appId}/publicData/comments`)
+);
+```
 
-// Get user token from your auth system
-const userToken = localStorage.getItem('authToken');
+### Use Case 2: User Private Settings
 
-// Generate Firestore token
-const firestoreToken = await client.generateFirestoreToken({
-  token: userToken,
-  app_id: 'my-app',
+```typescript
+// Only the user can write to their own settings
+await setDoc(doc(db, `appData/${appId}/userData/${userId}/settings/preferences`), {
+  _appId: appId,
+  _createdAt: serverTimestamp(),
+  _createdBy: userId,
+  theme: 'dark',
+  notifications: true,
+  language: 'en'
 });
 
-// Use the Firestore token to initialize Firebase
-import { initializeApp } from 'firebase/app';
-import { getFirestore } from 'firebase/firestore';
-import { signInWithCustomToken, getAuth } from 'firebase/auth';
-
-const firebaseApp = initializeApp({
-  projectId: firestoreToken.project_id,
-  // ... other Firebase config
-});
+// Only the user can read their own settings
+const settings = await getDoc(
+  doc(db, `appData/${appId}/userData/${userId}/settings/preferences`)
+);
+```
 
-const auth = getAuth(firebaseApp);
-await signInWithCustomToken(auth, firestoreToken.id_token);
+### Use Case 3: System Announcements (Admin Only)
 
-const db = getFirestore(firebaseApp);
-// Now you can use Firestore with the authenticated user
+```typescript
+// Only admins can write to publicRead
+// Regular users and guests can only read
+const announcements = await getDocs(
+  collection(db, `appData/${appId}/publicRead/announcements`)
+);
+
+announcements.forEach(doc => {
+  console.log('Announcement:', doc.data().message);
+});
 ```
 
-### Node.js Environment
+### Use Case 4: Querying Public Data
 
 ```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
+import { query, where, orderBy, limit } from 'firebase/firestore';
 
-const client = new DataServiceClient();
-
-async function getFirestoreAccess(userToken: string, appId: string) {
-  try {
-    const response = await client.generateFirestoreToken({
-      token: userToken,
-      app_id: appId,
-    });
-
-    return {
-      token: response.id_token,
-      projectId: response.project_id,
-      databaseId: response.database_id,
-      userId: response.user_id,
-      expiresIn: response.expires_in,
-    };
-  } catch (error) {
-    console.error('Error getting Firestore access:', error);
-    throw error;
-  }
-}
+// Query posts created by a specific user
+const userPosts = query(
+  collection(db, `appData/${appId}/publicData/posts`),
+  where('_createdBy', '==', userId),
+  orderBy('_createdAt', 'desc'),
+  limit(10)
+);
+
+const snapshot = await getDocs(userPosts);
 ```
 
-### Guest User Example
+## Permission Examples
 
-```typescript
-import { DataServiceClient } from '@seaverse/data-service-sdk';
+### What Users CAN Do
 
-const client = new DataServiceClient();
+✅ **Authenticated Users:**
+- Read `publicRead` data
+- Read and write `publicData` (all users' data)
+- Read and write their own `userData/{userId}` only
+- Update/delete documents where `_createdBy == userId`
 
-// For anonymous/guest users who don't have an account
-async function initializeGuestSession(appId: string) {
-  const guestToken = await client.generateGuestFirestoreToken({
-    app_id: appId,
-  });
+✅ **Guest Users:**
+- Read `publicRead` data
+- Read and write `publicData`
+- **Cannot** access any `userData`
 
-  // Initialize Firebase with guest token
-  const auth = getAuth(firebaseApp);
-  await signInWithCustomToken(auth, guestToken.id_token);
+✅ **Admin Users:**
+- Everything regular users can do
+- Write to `publicRead` data
 
-  console.log('Guest session initialized:', guestToken.user_id);
-}
-```
+### What Users CANNOT Do
 
-## Error Handling
+❌ **All Users:**
+- Access data from a different `app_id`
+- Create documents without required fields (`_appId`, `_createdAt`, `_createdBy`)
+- Modify documents created by other users (except in special cases)
+- Access another user's `userData`
+
+❌ **Guest Users:**
+- Access any `userData` paths
 
-The SDK automatically handles API response errors and throws meaningful error messages:
+## Error Handling
 
 ```typescript
 try {
   const token = await client.generateFirestoreToken({
     token: 'invalid-token',
-    app_id: 'my-app',
+    app_id: 'my-app'
   });
 } catch (error) {
   if (error instanceof Error) {
     console.error('Error:', error.message);
-    // Error messages come from the API response
+    // Handle error (e.g., invalid token, network error)
   }
 }
 ```
 
+Common errors:
+- `Invalid token` - JWT token is invalid or expired
+- `permission-denied` - Missing required fields or insufficient permissions
+- `Missing or insufficient permissions` - Trying to access unauthorized data
+
 ## TypeScript Support
 
 This SDK is written in TypeScript and provides full type definitions:
@@ -273,10 +380,129 @@ import type {
   GenerateGuestFirestoreTokenRequest,
   FirestoreTokenResponse,
   ApiResponse,
-  ApiError,
+  ApiError
 } from '@seaverse/data-service-sdk';
 ```
 
+## Best Practices for LLM
+
+When using this SDK with LLM-generated code:
+
+1. **Always include required fields:**
+   ```typescript
+   {
+     _appId: appId,              // From token response
+     _createdAt: serverTimestamp(), // Use serverTimestamp()
+     _createdBy: userId          // From token response
+   }
+   ```
+
+2. **Use correct data paths:**
+   - publicRead: `appData/${appId}/publicRead/{collection}/{docId}`
+   - publicData: `appData/${appId}/publicData/{collection}/{docId}`
+   - userData: `appData/${appId}/userData/${userId}/{collection}/{docId}`
+
+3. **Handle token expiration:**
+   - Tokens expire after 1 hour (3600 seconds)
+   - Check `expires_in` field and refresh when needed
+
+4. **Use serverTimestamp() for timestamps:**
+   ```typescript
+   import { serverTimestamp } from 'firebase/firestore';
+
+   {
+     _createdAt: serverTimestamp() // Not new Date()!
+   }
+   ```
+
+5. **Separate guest and authenticated flows:**
+   - Use `generateGuestFirestoreToken()` for anonymous users
+   - Use `generateFirestoreToken()` for logged-in users
+
+## Complete Example
+
+Here's a complete example combining authentication and data access:
+
+```typescript
+import { DataServiceClient } 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, query, where, serverTimestamp } from 'firebase/firestore';
+
+async function completeExample() {
+  const appId = 'my-app-123';
+
+  // 1. Authenticate user
+  const authClient = new AuthClient({ appId });
+  const loginResponse = await authClient.loginWithEmail({
+    email: 'user@example.com',
+    password: 'password123'
+  });
+
+  // 2. Get Firestore token
+  const dataClient = new DataServiceClient();
+  const firestoreToken = await dataClient.generateFirestoreToken({
+    token: loginResponse.token,
+    app_id: appId
+  });
+
+  // 3. Initialize Firebase
+  const app = initializeApp({ projectId: firestoreToken.project_id });
+  const auth = getAuth(app);
+  await signInWithCustomToken(auth, firestoreToken.custom_token);
+  const db = getFirestore(app);
+
+  const userId = firestoreToken.user_id;
+
+  // 4. Create a post (publicData)
+  const postRef = await addDoc(
+    collection(db, `appData/${appId}/publicData/posts`),
+    {
+      _appId: appId,
+      _createdAt: serverTimestamp(),
+      _createdBy: userId,
+      title: 'My First Post',
+      content: 'Hello world!',
+      tags: ['introduction', 'first-post']
+    }
+  );
+  console.log('Created post:', postRef.id);
+
+  // 5. Read all posts
+  const postsSnapshot = await getDocs(
+    collection(db, `appData/${appId}/publicData/posts`)
+  );
+  postsSnapshot.forEach(doc => {
+    console.log('Post:', doc.id, doc.data());
+  });
+
+  // 6. Query user's own posts
+  const myPostsQuery = query(
+    collection(db, `appData/${appId}/publicData/posts`),
+    where('_createdBy', '==', userId)
+  );
+  const myPosts = await getDocs(myPostsQuery);
+  console.log('My posts count:', myPosts.size);
+
+  // 7. Save user preferences (private)
+  await addDoc(
+    collection(db, `appData/${appId}/userData/${userId}/preferences`),
+    {
+      _appId: appId,
+      _createdAt: serverTimestamp(),
+      _createdBy: userId,
+      theme: 'dark',
+      language: 'en',
+      notifications: true
+    }
+  );
+  console.log('Saved user preferences');
+}
+
+completeExample();
+```
+
 ## API Endpoints
 
 The SDK connects to the following endpoints by default:
@@ -294,3 +520,8 @@ MIT
 For issues and questions, please visit:
 - GitHub: https://github.com/seaverseai/sv-sdk
 - Email: support@seaverse.com
+
+## Related SDKs
+
+- [@seaverse/auth-sdk](../auth-sdk) - User authentication and account management
+- [@seaverse/payment-sdk](../payment-sdk) - Payment processing integration