cocobase 1.2.1 → 1.3.2

package/README.md

@@ -12,7 +12,10 @@ Go from idea to MVP in minutes, not weeks. No server configuration, no database
 
 ```typescript
 // This is literally all you need to start
-const db = new Cocobase({ apiKey: "your-key" });
+const db = new Cocobase({
+  apiKey: "your-key",          // From cocobase.buzz
+  projectId: "your-project-id" // From cocobase.buzz
+});
 await db.createDocument("users", { name: "John" });
 ```
 
@@ -22,9 +25,11 @@ Built-in user management that actually works. Registration, login, sessions, and
 
 ```typescript
 // User registration + automatic login in one line
-await db.register("user@example.com", "password", { role: "admin" });
+await db.auth.register("user@example.com", "password", { role: "admin" });
 ```
 
+> 💡 **New in v1.3.1:** All auth methods now use the `db.auth.*` namespace for better organization. Old methods still work but are deprecated. See our [Migration Guide](docs/Migration-Guide.md).
+
 ### 📊 **Real-time Data Management**
 
 Store, retrieve, and manage your application data with a clean, intuitive API. No SQL knowledge required.
@@ -277,27 +282,71 @@ const posts = await db.listDocuments("posts");
 
 Ready to build something amazing? Here's how to get started:
 
-1. **Visit** [cocobase.buzz](https://cocobase.buzz)
-2. **Sign up** for a free account
-3. **Create** your first project
-4. **Install** the SDK: `npm install cocobase`
-5. **Start building** awesome things!
+### 1. Get Your Credentials
+
+1. **Visit** [cocobase.buzz](https://cocobase.buzz) and sign up for a free account
+2. **Create** your first project in the dashboard
+3. **Copy your credentials** from the project dashboard:
+   - **API Key** - Used to authenticate your requests
+   - **Project ID** - Identifies your project
+
+> 💡 **Where to find your credentials:**
+> After creating a project on [cocobase.buzz](https://cocobase.buzz), you'll find your **API Key** and **Project ID** in your project's dashboard. Keep these secure and never commit them to version control!
+
+### 2. Install the SDK
+
+```bash
+npm install cocobase
+```
+
+### 3. Start Building
 
 ```typescript
 import { Cocobase } from "cocobase";
 
-const db = new Cocobase({ apiKey: "your-api-key" });
+const db = new Cocobase({
+  apiKey: "your-api-key",        // Get from cocobase.buzz
+  projectId: "your-project-id"   // Get from cocobase.buzz
+});
 
 // You're ready to build! 🎉
 ```
 
+## 🆕 What's New in v1.3.1
+
+### New Authentication Handler Architecture
+
+All authentication methods are now organized under the `db.auth.*` namespace for better code organization and maintainability:
+
+```typescript
+// ✅ New way (recommended)
+await db.auth.login("user@example.com", "password");
+const user = db.auth.getUser();
+const token = db.auth.getToken();
+
+// ❌ Old way (deprecated but still works)
+await db.login("user@example.com", "password");
+const user = db.user;
+const token = db.getToken();
+```
+
+**Benefits:**
+- 🏗️ Better code organization
+- 📚 Comprehensive JSDoc documentation
+- 🔄 Enhanced state management
+- 🛡️ Improved error handling
+
+**Migration:** Old methods still work but are deprecated. See our **[Migration Guide](docs/Migration-Guide.md)** for easy upgrade instructions.
+
 ## 📚 Resources
 
 - **[Documentation](https://docs.cocobase.buzz)** - Comprehensive guides and API reference
+- **[Migration Guide](docs/Migration-Guide.md)** - Upgrade from deprecated auth methods
 - **[Examples](https://github.com/cocobase/examples)** - Sample projects and tutorials
 - **[Community](https://discord.gg/cocobase)** - Join our developer community
 - **[Blog](https://blog.cocobase.buzz)** - Tips, tutorials, and updates
 - **[Status](https://status.cocobase.buzz)** - Service status and uptime
+- **[Changelog](CHANGELOG.md)** - See what's new in each version
 
 ## 🤝 Community & Support
 

package/dist/cjs/core/auth.d.ts

@@ -0,0 +1,356 @@
+import { CocobaseConfig, AppUser, AppUserList, Query, AuthCallbacks } from "../types/types.js";
+/**
+ * Authentication handler for Cocobase client.
+ *
+ * Provides methods for user authentication, registration, and user management.
+ * This class handles all authentication-related operations and maintains user session state.
+ *
+ * @example
+ * ```typescript
+ * const db = new Cocobase({ apiKey: 'your-key' });
+ * await db.auth.login('user@example.com', 'password');
+ * ```
+ */
+export declare class AuthHandler {
+    private baseURL;
+    private apiKey?;
+    private token?;
+    private user?;
+    private callbacks;
+    /**
+     * Creates a new AuthHandler instance.
+     *
+     * @param config - Cocobase configuration
+     */
+    constructor(config: CocobaseConfig);
+    /**
+     * Register callbacks for authentication events.
+     * This allows your application to respond to auth state changes in a framework-agnostic way.
+     *
+     * @param callbacks - Object containing callback functions for various auth events
+     *
+     * @example
+     * ```typescript
+     * // React example
+     * db.auth.onAuthEvent({
+     *   onLogin: (user, token) => {
+     *     setUser(user);
+     *     setIsAuthenticated(true);
+     *   },
+     *   onLogout: () => {
+     *     setUser(null);
+     *     setIsAuthenticated(false);
+     *   },
+     *   onUserUpdate: (user) => {
+     *     setUser(user);
+     *   }
+     * });
+     *
+     * // Vue example
+     * db.auth.onAuthEvent({
+     *   onLogin: (user, token) => {
+     *     store.commit('setUser', user);
+     *     store.commit('setToken', token);
+     *   },
+     *   onLogout: () => {
+     *     store.commit('clearAuth');
+     *   }
+     * });
+     *
+     * // Svelte example
+     * db.auth.onAuthEvent({
+     *   onLogin: (user, token) => {
+     *     userStore.set(user);
+     *     tokenStore.set(token);
+     *   },
+     *   onLogout: () => {
+     *     userStore.set(null);
+     *     tokenStore.set(null);
+     *   }
+     * });
+     * ```
+     */
+    onAuthEvent(callbacks: AuthCallbacks): void;
+    /**
+     * Remove all registered callbacks.
+     */
+    clearAuthCallbacks(): void;
+    /**
+     * Gets the current authentication token.
+     *
+     * @returns The current JWT token, or undefined if not authenticated
+     */
+    getToken(): string | undefined;
+    /**
+     * Sets the authentication token and stores it in local storage.
+     
+     * @param token - JWT authentication token
+     */
+    setToken(token: string): void;
+    /**
+     * Updates the current user object.
+     *
+     * @param user - User object to set
+     */
+    setUser(user: AppUser): void;
+    /**
+     * Gets the current user object.
+     *
+     * @returns The current user, or undefined if not authenticated
+     */
+    getUser(): AppUser | undefined;
+    /**
+     * Makes an authenticated request to the API.
+     *
+     * @private
+     * @param method - HTTP method
+     * @param path - API endpoint path
+     * @param body - Request body
+     * @param useDataKey - Whether to wrap body in data key
+     * @returns Promise resolving to response data
+     */
+    private request;
+    /**
+     * Provides error suggestions based on HTTP status codes.
+     *
+     * @private
+     * @param status - HTTP status code
+     * @param method - HTTP method used
+     * @returns Suggestion string
+     */
+    private getErrorSuggestion;
+    /**
+     * Initializes authentication by restoring the session from local storage.
+     * Call this method when your application loads to restore user sessions.
+     *
+     * @example
+     * ```typescript
+     * await db.auth.initAuth();
+     * if (db.auth.isAuthenticated()) {
+     *   console.log('User is logged in:', db.auth.getUser());
+     * }
+     * ```
+     */
+    initAuth(): Promise<void>;
+    /**
+     * Authenticates a user with email and password.
+     *
+     * @param email - User's email address
+     * @param password - User's password
+     * @returns Promise that resolves when login is complete
+     *
+     * @example
+     * ```typescript
+     * await db.auth.login('user@example.com', 'password123');
+     * console.log('Logged in as:', db.auth.getUser()?.email);
+     * ```
+     */
+    login(email: string, password: string): Promise<void>;
+    /**
+     * Registers a new user with email, password, and optional additional data.
+     *
+     * @param email - User's email address
+     * @param password - User's password
+     * @param data - Optional additional user data
+     * @returns Promise that resolves when registration is complete
+     *
+     * @example
+     * ```typescript
+     * await db.auth.register('user@example.com', 'password123', {
+     *   username: 'johndoe',
+     *   fullName: 'John Doe'
+     * });
+     * ```
+     */
+    register(email: string, password: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Authenticates a user using Google Sign-In with ID token.
+     *
+     * This method verifies the Google ID token and either creates a new user
+     * or logs in an existing user who registered with Google OAuth.
+     *
+     * @param idToken - Google ID token obtained from Google Sign-In
+     * @param platform - Optional platform identifier ('web', 'mobile', 'ios', 'android')
+     * @returns Promise resolving to the authenticated user object
+     *
+     * @throws {Error} If Google Sign-In is not enabled in project settings
+     * @throws {Error} If the Google ID token is invalid or expired
+     * @throws {Error} If email is already registered with password authentication
+     * @throws {Error} If email is already registered with Apple Sign-In
+     *
+     * @example
+     * ```typescript
+     * // Web - Using Google Identity Services
+     * google.accounts.id.initialize({
+     *   client_id: 'YOUR_GOOGLE_CLIENT_ID',
+     *   callback: async (response) => {
+     *     const user = await db.auth.loginWithGoogle(response.credential, 'web');
+     *     console.log('Logged in:', user.email);
+     *   }
+     * });
+     *
+     * // Mobile - After getting ID token from Google Sign-In SDK
+     * const user = await db.auth.loginWithGoogle(idToken, 'mobile');
+     * ```
+     */
+    loginWithGoogle(idToken: string, platform?: "web" | "mobile" | "ios" | "android"): Promise<AppUser>;
+    /**
+     * Register a new user with file uploads (avatar, cover photo, etc.)
+     *
+     * @param email - User email
+     * @param password - User password
+     * @param data - Additional user data (optional)
+     * @param files - Object mapping field names to File objects (optional)
+     *
+     * @example
+     * ```typescript
+     * // Register with avatar
+     * await db.auth.registerWithFiles(
+     *   'john@example.com',
+     *   'password123',
+     *   { username: 'johndoe', full_name: 'John Doe' },
+     *   { avatar: avatarFile }
+     * );
+     *
+     * // Register with avatar and cover photo
+     * await db.auth.registerWithFiles(
+     *   'john@example.com',
+     *   'password123',
+     *   { username: 'johndoe' },
+     *   { avatar: avatarFile, cover_photo: coverFile }
+     * );
+     * ```
+     */
+    registerWithFiles(email: string, password: string, data?: Record<string, any>, files?: Record<string, File | File[]>): Promise<AppUser>;
+    /**
+     * Logs out the current user by clearing the token and user data.
+     *
+     * @example
+     * ```typescript
+     * db.auth.logout();
+     * console.log('User logged out');
+     * ```
+     */
+    logout(): void;
+    /**
+     * Checks if a user is currently authenticated.
+     *
+     * @returns True if user is authenticated, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (db.auth.isAuthenticated()) {
+     *   console.log('User is logged in');
+     * }
+     * ```
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Fetches the current authenticated user's data from the server.
+     *
+     * @returns Promise resolving to the current user object
+     *
+     * @example
+     * ```typescript
+     * const user = await db.auth.getCurrentUser();
+     * console.log('Current user:', user.email);
+     * ```
+     */
+    getCurrentUser(): Promise<AppUser>;
+    /**
+     * Updates the current user's profile data.
+     *
+     * @param data - User data to update (optional)
+     * @param email - New email address (optional)
+     * @param password - New password (optional)
+     * @returns Promise resolving to the updated user object
+     *
+     * @example
+     * ```typescript
+     * await db.auth.updateUser({
+     *   bio: 'Updated bio',
+     *   website: 'https://example.com'
+     * });
+     * ```
+     */
+    updateUser(data?: Record<string, any> | null, email?: string | null, password?: string | null): Promise<AppUser>;
+    /**
+     * Update current user with file uploads
+     *
+     * @param data - User data to update (optional)
+     * @param email - New email (optional)
+     * @param password - New password (optional)
+     * @param files - Object mapping field names to File objects (optional)
+     *
+     * @example
+     * ```typescript
+     * // Update only avatar
+     * await db.auth.updateUserWithFiles(
+     *   undefined, undefined, undefined,
+     *   { avatar: newAvatarFile }
+     * );
+     *
+     * // Update bio and avatar
+     * await db.auth.updateUserWithFiles(
+     *   { bio: 'Updated bio' },
+     *   undefined, undefined,
+     *   { avatar: newAvatarFile }
+     * );
+     *
+     * // Update multiple fields and files
+     * await db.auth.updateUserWithFiles(
+     *   { username: 'newusername', bio: 'New bio' },
+     *   'newemail@example.com',
+     *   undefined,
+     *   { avatar: newAvatar, cover_photo: newCover }
+     * );
+     * ```
+     */
+    updateUserWithFiles(data?: Record<string, any> | null, email?: string | null, password?: string | null, files?: Record<string, File | File[]>): Promise<AppUser>;
+    /**
+     * Checks if the current user has a specific role.
+     *
+     * @param role - Role to check for
+     * @returns True if user has the role, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (db.auth.hasRole('admin')) {
+     *   console.log('User is an admin');
+     * }
+     * ```
+     */
+    hasRole(role: string): boolean;
+    /**
+     * Lists users from the auth collection with optional filtering and pagination.
+     *
+     * @template T - The type of user data
+     * @param query - Optional query parameters for filtering, sorting, and pagination
+     * @returns Promise resolving to a list of users
+     *
+     * @example
+     * ```typescript
+     * const users = await db.auth.listUsers({
+     *   filters: { status: 'active' },
+     *   limit: 10
+     * });
+     * ```
+     */
+    listUsers<T = any>(query?: Query): Promise<AppUserList>;
+    /**
+     * Gets a user by their ID.
+     *
+     * @template T - The type of user data
+     * @param userId - Unique ID of the user
+     * @returns Promise resolving to the user object
+     *
+     * @example
+     * ```typescript
+     * const user = await db.auth.getUserById('user-123');
+     * console.log('User:', user.email);
+     * ```
+     */
+    getUserById<T = any>(userId: string): Promise<AppUser>;
+}
+export default AuthHandler;
+//# sourceMappingURL=auth.d.ts.map

package/dist/cjs/core/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/core/auth.ts"],"names":[],"mappings":"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"}