edmaxlabs-core 1.3.6 → 1.3.7

package/README.md

@@ -1,20 +1,19 @@
-## What is edmaxlabs-core?
+# EdmaxLabs Core SDK
 
-`edmaxlabs-core` is designed to be used directly inside your applications (React, vanilla JavaScript, Node.js, and more).
+[![npm version](https://badge.fury.io/js/edmaxlabs-core.svg)](https://badge.fury.io/js/edmaxlabs-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-It acts as the bridge between your app and EdmaxLabs infrastructure, handling communication, real-time updates, and secure data access.
+`edmaxlabs-core` is the official SDK for EdmaxLabs services, providing seamless integration with Authentication, Database, Storage, and Cloud Functions. **Framework agnostic** - works with any JavaScript framework or vanilla JS.
 
----
-
-## Features
+## 🚀 Features
 
-* Authentication
-* Database (with realtime support)
-* Cloud Storage
-* Cloud Functions
-* Framework-agnostic (React, Node.js, plain JS)
-
----
+- **Authentication** - Secure user authentication
+- **Database** - Real-time database with offline support
+- **Storage** - File upload/download
+- **Cloud Functions** - Serverless function execution
+- **Framework Agnostic** - Works with React, Vue, Angular, vanilla JS, Node.js
+- **Offline Support** - Automatic sync when online
+- **TypeScript** - Full TypeScript support
 
 ## 📦 Installation
 
@@ -22,32 +21,258 @@ It acts as the bridge between your app and EdmaxLabs infrastructure, handling co
 npm install edmaxlabs-core
 ```
 
----
+## 🧠 Quick Start
+
+### Basic Usage
+
+```typescript
+import EdmaxLabs from "edmaxlabs-core";
+
+const app = new EdmaxLabs({
+  token: "your-api-token",
+  project: "your-project-id",
+  enableOffline: true, // Enable offline persistence
+});
+
+// Get data
+const messages = await app.getDatabase.collection("messages").get();
+console.log(messages);
+```
 
-## 🧠 Quick Example
+### React Integration (Recommended)
 
-```ts
-import { EdmaxLabs } from "edmaxlabs-core";
+```tsx
+import EdmaxLabs from "edmaxlabs-core";
 
 const app = new EdmaxLabs({
   token: "your-token",
   project: "your-project-id",
-  persistence: true, // optional (offline support)
+  enableOffline: true,
 });
 
-const data = await app.database.collection("messages").get();
-//const data = await app.database.collection("messages").doc("docid").get();
-//...and more
-console.log(data);
+function ChatApp() {
+  const [messages, setMessages] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const unsubscribe = app.getDatabase.collection("messages").onSnapshot(
+      (docs) => {
+        setMessages(docs.map(doc => doc.data()));
+        setLoading(false);
+      }
+    );
+    return unsubscribe; // Important: cleanup to prevent memory leaks
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {messages.map(msg => (
+        <div key={msg.id}>{msg.text}</div>
+      ))}
+    </div>
+  );
+}
+```
+    <div>
+      {messages.map(msg => (
+        <div key={msg.id}>{msg.text}</div>
+      ))}
+    </div>
+  );
+}
 ```
 
----
+## 🔧 Configuration
+
+```typescript
+const app = new EdmaxLabs({
+  token: "your-api-token",           // Required: Your API token
+  project: "your-project-id",        // Required: Project identifier
+  baseUrl: "https://api.edmaxlabs.com", // Optional: API endpoint
+  enableOffline: true,               // Optional: Enable offline persistence
+  appName: "my-app",                 // Optional: Unique app identifier
+});
+```
+
+## 📚 API Reference
+
+### Database Operations
+
+```typescript
+// Get collection
+const collection = app.getDatabase.collection("users");
+
+// Get all documents
+const users = await collection.get();
+
+// Get specific document
+const user = await collection.doc("user-id").get();
+
+// Create/update document
+await collection.doc("user-id").set({
+  name: "John Doe",
+  email: "john@example.com"
+});
+
+// Update document
+await collection.doc("user-id").update({
+  lastLogin: new Date()
+});
+
+// Delete document
+await collection.doc("user-id").delete();
+
+// Real-time listeners
+const unsubscribe = collection.onSnapshot((snapshot) => {
+  console.log("Collection updated:", snapshot.docs);
+});
+```
+
+### Real-time Listeners
+
+```typescript
+// Document listener
+const unsubscribeDoc = app.getDatabase.collection("users").doc("user-id").onSnapshot(
+  (snapshot, change) => {
+    console.log("Document:", snapshot?.data());
+  }
+);
+
+// Collection listener
+const unsubscribeCollection = app.getDatabase.collection("messages").onSnapshot(
+  (documents, change) => {
+    console.log("Messages:", documents.map(doc => doc.data()));
+  }
+);
+
+// Cleanup when done
+unsubscribeDoc();
+unsubscribeCollection();
+```
+
+### Storage Operations
+
+```typescript
+// Upload file
+const ref = app.getStorage.ref("avatars/user-id.jpg");
+await ref.put(file);
+
+// Get download URL
+const url = await ref.getDownloadURL();
+
+// Delete file
+await ref.delete();
+```
+
+### Authentication
+
+```typescript
+// Get current user
+const user = app.getAuthentication.currentUser;
+
+// Listen to auth changes
+const unsubscribe = app.getAuthentication.onAuthStateChanged((user) => {
+  console.log("User:", user);
+});
+```
+
+## 🛡️ Production Considerations
+
+### Memory Leak Prevention
+
+**Always cleanup listeners** when components unmount:
+
+```tsx
+function MyComponent() {
+  useEffect(() => {
+    const unsubscribe = app.getDatabase.collection("items").onSnapshot(callback);
+    return unsubscribe; // ✅ Critical: prevent memory leaks
+  }, []);
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await app.getDatabase.collection("users").doc("id").set(data);
+} catch (error) {
+  if (error.message.includes("quota exceeded")) {
+    // Handle storage full
+    alert("Storage is full. Please clear data.");
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await app.getDatabase.collection("users").doc("id").set(data);
+} catch (error) {
+  if (error.message.includes("quota exceeded")) {
+    // Handle storage full
+    alert("Storage is full. Please clear some data.");
+  } else if (error.message.includes("Network")) {
+    // Handle offline
+    console.log("Will sync when online");
+  }
+}
+```
+
+### Storage Limits
+
+Monitor storage usage to prevent quota issues:
+
+```typescript
+const { usage } = await app.getStorageUsage();
+if (usage && usage.used > usage.available * 0.8) {
+  console.warn("Storage usage is over 80%");
+}
+```
+
+### Input Validation
+
+The SDK validates inputs automatically, but you should also validate:
+
+```typescript
+// These will throw errors:
+await doc.set(null);           // Error: data cannot be null
+await doc.set({ id: "123" });  // Error: 'id' is reserved
+await doc.set([]);             // Error: data cannot be an array
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Type checking
+npm run lint
+```
+
+## 📖 Documentation
+
+- [Full API Reference](https://edmaxlabs.com/docs/api)
+- [Migration Guide](https://edmaxlabs.com/docs/migration)
+- [Best Practices](https://edmaxlabs.com/docs/best-practices)
+
+## 🤝 Contributing
 
-## 📚 Documentation
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).
 
-For full guides, API references, and advanced usage:
+## 📄 License
 
-- [https://edmaxlabs.com/docs/get-started](https://edmaxlabs.com/docs/get-started)
+MIT License - see [LICENSE](LICENSE) file for details.
 - [https://edmaxlabs.com/docs/database](https://edmaxlabs.com/docs/database)
 - [https://edmaxlabs.com/docs/realtime](https://edmaxlabs.com/docs/realtime)
 - [https://edmaxlabs.com/docs/offline](https://edmaxlabs.com/docs/offline)