@seaverse/data-service-sdk 0.6.0 → 0.7.0

package/README.md

@@ -2,6 +2,18 @@
 
 SeaVerse Data Service SDK for accessing Firestore with secure token management and three-tier permission model.
 
+## 🤖 For LLM Users
+
+**👉 Want the simplest way to use this SDK? Check out the [LLM Quick Start Guide](./LLM-QUICK-START.md)**
+
+The Quick Start guide shows you the **recommended LLM-friendly API** that automatically handles:
+- ✅ Required fields (`_appId`, `_createdAt`, `_createdBy`)
+- ✅ Correct Firestore paths
+- ✅ Server timestamps
+- ✅ Single import source
+
+**Most common LLM mistakes prevented!**
+
 ## Features
 
 - 🔐 Secure Firestore token generation for authenticated users and guests
@@ -232,17 +244,11 @@ getUserDataPath('my-app', '', 'notes');  // Error: userId must be non-empty
 
 ## Quick Start
 
-### 🚀 Easiest Way (Recommended - Auto Firebase Setup)
+### 🚀 Easiest Way (🤖 LLM-Recommended)
 
 ```typescript
-import {
-  DataServiceClient,
-  initializeWithToken,
-  getPublicDataPath,  // 🛡️ Use path helpers!
-  getUserDataPath     // 🛡️ Use path helpers!
-} from '@seaverse/data-service-sdk';
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
 import { AuthClient } from '@seaverse/auth-sdk';
-import { collection, addDoc, getDocs, serverTimestamp } from 'firebase/firestore';
 
 // Step 1: Login user
 const authClient = new AuthClient({ appId: 'my-app-123' });
@@ -258,47 +264,65 @@ const tokenResponse = await dataClient.generateFirestoreToken({
   app_id: 'my-app-123'
 });
 
-// Step 3: Auto-initialize Firebase (ONE LINE!)
-const { db, appId, userId } = await initializeWithToken(tokenResponse);
+// Step 3: Initialize Firebase & get helper
+const { helper } = await initializeWithToken(tokenResponse);
 
-// Step 4: Use Firestore directly with path helpers!
+// Step 4: Use Firestore with helper (automatic required fields!)
 
-// Write to publicData (everyone can write)
-const postsPath = getPublicDataPath(appId, 'posts');  // 🛡️ Safe path!
-await addDoc(collection(db, postsPath), {
-  _appId: appId,              // REQUIRED
-  _createdAt: serverTimestamp(), // REQUIRED
-  _createdBy: userId,         // REQUIRED
+// ✅ LLM-FRIENDLY: Write to publicData - required fields auto-injected!
+await helper.addToPublicData('posts', {
   title: 'My First Post',
   content: 'Hello world!'
 });
 
-// Read from publicData
-const snapshot = await getDocs(collection(db, postsPath));
-snapshot.forEach(doc => {
+// ✅ LLM-FRIENDLY: Read from publicData
+const posts = await helper.getPublicData('posts');
+posts.forEach(doc => {
   console.log(doc.id, doc.data());
 });
 
-// Write to userData (private)
-const notesPath = getUserDataPath(appId, userId, 'notes');  // 🛡️ Safe path!
-await addDoc(collection(db, notesPath), {
-  _appId: appId,              // REQUIRED
-  _createdAt: serverTimestamp(), // REQUIRED
-  _createdBy: userId,         // REQUIRED
+// ✅ LLM-FRIENDLY: Write to userData (private) - auto-isolated!
+await helper.addToUserData('notes', {
   title: 'Private Note',
   content: 'Only I can see this'
 });
 ```
 
-### 👤 For Guest Users (Even Simpler!)
+<details>
+<summary>📖 Advanced: Manual Way (for fine-grained control)</summary>
 
 ```typescript
 import {
   DataServiceClient,
   initializeWithToken,
-  getPublicDataPath  // 🛡️ Use path helpers!
+  getPublicDataPath,
+  getUserDataPath,
+  collection,
+  addDoc,
+  getDocs,
+  serverTimestamp
 } from '@seaverse/data-service-sdk';
-import { collection, addDoc, serverTimestamp } from 'firebase/firestore';
+import { AuthClient } from '@seaverse/auth-sdk';
+
+// ... login and initialize ...
+const { db, appId, userId } = await initializeWithToken(tokenResponse);
+
+// Manual way: Use path helpers + required fields
+const postsPath = getPublicDataPath(appId, 'posts');
+await addDoc(collection(db, postsPath), {
+  _appId: appId,              // REQUIRED
+  _createdAt: serverTimestamp(), // REQUIRED
+  _createdBy: userId,         // REQUIRED
+  title: 'My First Post',
+  content: 'Hello world!'
+});
+```
+</details>
+
+### 👤 For Guest Users (🤖 Even Simpler!)
+
+```typescript
+import { DataServiceClient, initializeWithToken } from '@seaverse/data-service-sdk';
 
 // Step 1: Get guest token (no authentication needed!)
 const dataClient = new DataServiceClient();
@@ -306,15 +330,11 @@ const tokenResponse = await dataClient.generateGuestFirestoreToken({
   app_id: 'my-app-123'
 });
 
-// Step 2: Auto-initialize Firebase (ONE LINE!)
-const { db, appId, userId } = await initializeWithToken(tokenResponse);
+// Step 2: Initialize & get helper
+const { helper } = await initializeWithToken(tokenResponse);
 
-// Step 3: Guest can write to publicData
-const commentsPath = getPublicDataPath(appId, 'comments');  // 🛡️ Safe path!
-await addDoc(collection(db, commentsPath), {
-  _appId: appId,
-  _createdAt: serverTimestamp(),
-  _createdBy: userId,  // Guest user ID (e.g., 'guest-abc123')
+// Step 3: Guest can write to publicData (automatic required fields!)
+await helper.addToPublicData('comments', {
   comment: 'Great app!',
   rating: 5
 });