@basictech/react 0.7.0-beta.5 → 0.7.0-beta.7

package/readme.md

@@ -1,6 +1,6 @@
 # @basictech/react
 
-A React package for integrating Basic authentication and database functionality into your React applications.
+React SDK for [Basic](https://basic.tech) - add authentication and real-time database to your React app in minutes.
 
 ## Installation
 
@@ -8,298 +8,292 @@ A React package for integrating Basic authentication and database functionality
 npm install @basictech/react
 ```
 
-## Usage
+## Quick Start
 
-### 1. Wrap your application with BasicProvider
+### 1. Create a Schema
 
-In your root component or App.tsx, wrap your application with the `BasicProvider`:
+Create a `basic.config.ts` file with your project configuration:
 
 ```typescript
-import { BasicProvider } from '@basictech/react';
-
-const schema = {
-  tables: { 
-    todos: { 
-      fields: { 
-        id: { 
-          type: "string",
-          primary: true
-        },
-        title: { 
-          type: "string",
-          indexed: true
-        },
-        completed: { 
-          type: "boolean",
-          indexed: true
-        }
+export const schema = {
+  project_id: "YOUR_PROJECT_ID",
+  version: 1,
+  tables: {
+    todos: {
+      type: "collection",
+      fields: {
+        title: { type: "string", indexed: true },
+        completed: { type: "boolean", indexed: true }
       }
     }
-  } 
+  }
 }
+```
+
+### 2. Add the Provider
 
+Wrap your app with `BasicProvider`:
+
+```tsx
+import { BasicProvider } from '@basictech/react'
+import { schema } from './basic.config'
 
 function App() {
   return (
-    <BasicProvider project_id="YOUR_PROJECT_ID" schema={schema} debug>
-      {/* Your app components */}
+    <BasicProvider schema={schema}>
+      <YourApp />
     </BasicProvider>
-  );
+  )
 }
-
-export default App;
 ```
 
-Replace `YOUR_PROJECT_ID` with your actual Basic project ID.
+### 3. Use the Hook
 
-### 2. Use the useBasic hook
+Access auth and database in any component:
 
-In your components, you can use the `useBasic` hook to access authentication and database functionality:
+```tsx
+import { useBasic, useQuery } from '@basictech/react'
 
-```typescript
-import { useBasic } from '@basictech/react';
+function TodoList() {
+  const { db, isSignedIn, signIn, signOut, user } = useBasic()
+  
+  // Live query - automatically updates when data changes
+  const todos = useQuery(() => db.collection('todos').getAll())
 
-function MyComponent() {
-  const { user, isSignedIn, signin, signout, signinWithCode, db } = useBasic();
+  const addTodo = async () => {
+    await db.collection('todos').add({
+      title: 'New todo',
+      completed: false
+    })
+  }
 
   if (!isSignedIn) {
-    return <button onClick={signin}>Sign In</button>;
+    return <button onClick={signIn}>Sign In</button>
   }
 
   return (
     <div>
-      <h1>Welcome, {user.name}!</h1>
-      <button onClick={signout}>Sign Out</button>
+      <p>Welcome, {user?.email}</p>
+      <button onClick={addTodo}>Add Todo</button>
+      <ul>
+        {todos?.map(todo => (
+          <li key={todo.id}>{todo.title}</li>
+        ))}
+      </ul>
+      <button onClick={signOut}>Sign Out</button>
     </div>
-  );
+  )
 }
 ```
 
-### 3. Manual OAuth Code Handling
-
-For custom OAuth flows (mobile apps, server-side redirects, etc.), you can manually handle authorization codes:
+---
 
-```typescript
-import { useBasic } from '@basictech/react';
-
-function CustomAuthComponent() {
-  const { signinWithCode } = useBasic();
-
-  const handleOAuthCode = async (code: string, state?: string) => {
-    const result = await signinWithCode(code, state);
-    
-    if (result.success) {
-      console.log('Successfully authenticated!');
-      // Redirect to authenticated area
-    } else {
-      console.error('Authentication failed:', result.error);
-      // Handle error
-    }
-  };
-
-  // Example: Handle OAuth code from URL parameters
-  useEffect(() => {
-    const urlParams = new URLSearchParams(window.location.search);
-    const code = urlParams.get('code');
-    const state = urlParams.get('state');
-    
-    if (code) {
-      handleOAuthCode(code, state || undefined);
-    }
-  }, []);
+## API Reference
 
-  return <div>Processing authentication...</div>;
-}
-```
+### `<BasicProvider>`
 
-#### Mobile App Integration Example:
+Root provider component. Must wrap your entire app.
 
-```typescript
-// React Native or mobile app deep link handling
-const handleDeepLink = (url: string) => {
-  const urlParams = new URLSearchParams(url.split('?')[1]);
-  const code = urlParams.get('code');
-  const state = urlParams.get('state');
-  
-  if (code) {
-    signinWithCode(code, state || undefined);
-  }
-};
+```tsx
+<BasicProvider
+  schema={schema}           // Required: Your Basic schema
+  debug={false}             // Optional: Enable console logging
+  dbMode="sync"             // Optional: "sync" (default) or "remote"
+/>
 ```
 
-#### Server-Side OAuth Example:
+#### Props
 
-```typescript
-// When OAuth happens server-side and you receive the code
-const handleServerOAuth = async (serverCode: string) => {
-  const result = await signinWithCode(serverCode);
-  
-  if (result.success) {
-    // Redirect to authenticated area
-    window.location.href = '/dashboard';
-  } else {
-    // Show error message
-    alert(`Authentication failed: ${result.error}`);
-  }
-};
-```
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `schema` | `object` | required | Schema with `project_id` and `tables` |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `dbMode` | `"sync" \| "remote"` | `"sync"` | Database mode |
 
-### 4. Custom OAuth Redirect URIs
+#### Database Modes
 
-You can specify custom redirect URIs for OAuth flows:
+- **`sync`** - Local-first with IndexedDB + real-time sync via WebSocket
+- **`remote`** - Direct REST API calls (no local storage)
 
-```typescript
-import { useBasic } from '@basictech/react';
-
-function CustomAuthComponent() {
-  const { getSignInLink } = useBasic();
+---
 
-  const handleCustomRedirect = () => {
-    // Use a custom redirect URI
-    const signInUrl = getSignInLink('https://yourapp.com/auth/callback');
-    window.location.href = signInUrl;
-  };
+### `useBasic()`
 
-  const handleDefaultRedirect = () => {
-    // Use default redirect (current page URL)
-    const signInUrl = getSignInLink();
-    window.location.href = signInUrl;
-  };
+Main hook for accessing auth and database.
 
-  return (
-    <div>
-      <button onClick={handleCustomRedirect}>
-        Sign In (Custom Redirect)
-      </button>
-      <button onClick={handleDefaultRedirect}>
-        Sign In (Default Redirect)
-      </button>
-    </div>
-  );
-}
+```tsx
+const {
+  // Auth state
+  isReady,        // boolean - SDK initialized
+  isSignedIn,     // boolean - User authenticated
+  user,           // { id, email, ... } | null
+  
+  // Auth methods
+  signIn,         // () => void - Redirect to login
+  signOut,        // () => void - Clear session
+  signInWithCode, // (code, state?) => Promise - Manual OAuth
+  getSignInUrl,   // (redirectUri?) => string - Get OAuth URL
+  getToken,       // () => Promise<string> - Get access token
+  
+  // Database
+  db,             // Database instance
+  dbStatus,       // "OFFLINE" | "CONNECTING" | "ONLINE" | "SYNCING"
+  dbMode,         // "sync" | "remote"
+} = useBasic()
 ```
 
-#### Use Cases for Custom Redirect URIs:
+---
 
-- **Mobile Apps**: Redirect to app-specific URLs
-- **Multi-Domain**: Redirect to different domains based on context
-- **Testing**: Use test-specific callback URLs
-- **Subdomains**: Redirect to specific subdomains
+### `useQuery()`
 
-## API Reference
+Live query hook - automatically re-renders when data changes.
 
+```tsx
+import { useQuery } from '@basictech/react'
 
-### <BasicProvider>
+// Get all items
+const todos = useQuery(() => db.collection('todos').getAll())
 
-The `BasicProvider` component accepts the following props:
+// With type safety
+interface Todo {
+  id: string
+  title: string
+  completed: boolean
+}
+const todos = useQuery(() => db.collection<Todo>('todos').getAll())
+```
 
-- `project_id` (required): String - Your Basic project ID.
-- `schema` (required): Object - The schema definition for your database.
-- `debug` (optional): Boolean - Enable debug mode for additional logging. Default is `false`.
-- `children` (required): React.ReactNode - The child components to be wrapped by the provider.
+> **Note:** Only works in `sync` mode. In `remote` mode, use manual fetching.
 
+---
 
+### Database Methods
 
+#### `db.collection(name)`
 
-### useQuery
+Access a collection by name.
 
-returns a react hook that will automatically update data based on your query 
+```tsx
+const { db } = useBasic()
+const todos = db.collection('todos')
+```
 
-usage: 
+#### Collection Methods
 
-```typescript
-import { useQuery } from '@basictech/react'
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getAll()` | `Promise<T[]>` | Get all records |
+| `get(id)` | `Promise<T \| null>` | Get one record by ID |
+| `add(data)` | `Promise<T>` | Create new record (returns with ID) |
+| `put(data)` | `Promise<T>` | Upsert record (requires ID) |
+| `update(id, data)` | `Promise<T \| null>` | Partial update |
+| `delete(id)` | `Promise<boolean>` | Delete record |
+| `filter(fn)` | `Promise<T[]>` | Filter with predicate |
 
-function MyComponent() {
-  const data = useQuery(db.collection('data').getAll())
+#### Examples
 
-  return (
-    <div>
-      { 
-        data.map((item: any) => {
-          <> 
-          // render your data here
-          </>
-        })
-      }
-    </div>
-  );
-}
-```
-Notes:
-- must pass in a db function, ie `db.collection('todos').getAll()`
-- default will be empty array (this might change in the future)
+```tsx
+// Create
+const todo = await db.collection('todos').add({
+  title: 'Buy milk',
+  completed: false
+})
+console.log(todo.id) // Auto-generated ID
 
+// Read
+const allTodos = await db.collection('todos').getAll()
+const oneTodo = await db.collection('todos').get('some-id')
 
-### useBasic()
+// Update
+await db.collection('todos').update('some-id', { completed: true })
 
-Returns an object with the following properties and methods:
+// Delete
+await db.collection('todos').delete('some-id')
 
-- `user`: The current user object
-- `isSignedIn`: Boolean indicating if the user is signed in
-- `signin()`: Function to initiate the sign-in process
-- `signout()`: Function to sign out the user
-- `signinWithCode(code: string, state?: string)`: Function to manually handle OAuth authorization codes
-- `getSignInLink(redirectUri?: string)`: Function to generate OAuth sign-in URLs
-- `db`: Object for database operations
+// Filter
+const incomplete = await db.collection('todos').filter(t => !t.completed)
+```
 
-#### signinWithCode Parameters:
-- `code` (required): The OAuth authorization code received from the OAuth provider
-- `state` (optional): The state parameter for CSRF protection validation
+---
 
-#### signinWithCode Returns:
-- `Promise<{ success: boolean, error?: string }>`: Returns success status and optional error message
+## Advanced Usage
 
-#### getSignInLink Parameters:
-- `redirectUri` (optional): Custom redirect URI for OAuth flow. If not provided, defaults to current page URL
+### Manual OAuth Flow
 
-#### getSignInLink Returns:
-- `string`: Complete OAuth authorization URL
+For custom OAuth handling (mobile apps, popups, etc.):
 
+```tsx
+const { signInWithCode, getSignInUrl } = useBasic()
 
+// Get OAuth URL with custom redirect
+const url = getSignInUrl('myapp://callback')
 
-db methods: 
+// Exchange code for session
+const result = await signInWithCode(code, state)
+if (result.success) {
+  console.log('Signed in!')
+}
+```
 
-- `collection(name: string)`: returns a collection object
+### Remote Mode
 
+For server-rendered apps or when you don't need offline support:
 
-db.collection(name) methods: 
+```tsx
+<BasicProvider schema={schema} dbMode="remote">
+  <App />
+</BasicProvider>
+```
 
-- `getAll()`: returns all items in the collection
-- `get(id: string)`: returns a single item from the collection
-- `add(data: any)`: adds a new item to the collection
-- `put(data: any)`: updates an item in the collection
-- `update(id: string, data: any)`: updates an item in the collection
-- `delete(id: string)`: deletes an item from the collection
+In remote mode:
+- Data is fetched via REST API
+- No IndexedDB storage
+- `useQuery` won't auto-update (use manual refresh)
+- Requires authentication for all operations
 
-all db.collection() methods return a promise 
+### Error Handling
 
-example usage: 
+```tsx
+import { NotAuthenticatedError } from '@basictech/react'
 
-```typescript
-import { useBasic } from '@basictech/react';
+try {
+  await db.collection('todos').add({ title: 'Test' })
+} catch (error) {
+  if (error instanceof NotAuthenticatedError) {
+    // User needs to sign in
+    signIn()
+  }
+}
+```
 
-function MyComponent() {
-  const { db } = useBasic();
+---
 
-  async function addTodo() {
-    await db.collection('todos').add({
-      title: 'test',
-      completed: false
-    })
-  }
+## TypeScript
 
-  return (
-    <div>
-      <button onClick={addTodo}>Add Todo</button>
-    </div>
-  );
+Full TypeScript support with generics:
+
+```tsx
+interface Todo {
+  id: string
+  title: string
+  completed: boolean
+  createdAt: number
 }
 
+// Type-safe collection
+const todos = db.collection<Todo>('todos')
+
+// All methods are typed
+const todo = await todos.add({
+  title: 'Test',
+  completed: false,
+  createdAt: Date.now()
+})
+// todo is typed as Todo
 ```
 
+---
+
 ## License
 
 ISC
-
----