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

package/src/AuthContext.tsx

@@ -1,7 +1,8 @@
 import React, { createContext, useContext, useEffect, useState, useRef } from 'react'
 import { jwtDecode } from 'jwt-decode'
 
-import { BasicSync } from './sync'
+import { BasicSync, initDexieExtensions } from './sync'
+import { RemoteDB, DBMode, BasicDB } from './core/db'
 
 import { log } from './config'
 import { version as currentVersion } from '../package.json'
@@ -12,6 +13,7 @@ import { isDevelopment, checkForNewVersion, cleanOAuthParamsFromUrl, getSyncStat
 import { getSchemaStatus, validateAndCheckSchema } from './utils/schema'
 
 export type { BasicStorage, LocalStorageAdapter } from './utils/storage'
+export type { DBMode, BasicDB, Collection } from './core/db'
 
 export type AuthConfig = {
     scopes?: string | string[];
@@ -21,11 +23,22 @@ export type AuthConfig = {
 
 export type BasicProviderProps = {
     children: React.ReactNode;
+    /** 
+     * @deprecated Project ID is now extracted from schema.project_id. 
+     * This prop is kept for backward compatibility but can be omitted.
+     */
     project_id?: string;
+    /** The Basic schema object containing project_id and table definitions */
     schema?: any;
     debug?: boolean;
     storage?: BasicStorage;
     auth?: AuthConfig;
+    /**
+     * Database mode - determines which implementation is used
+     * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
+     * - 'remote': Uses REST API calls directly to server
+     */
+    dbMode?: DBMode;
 }
 
 const DEFAULT_AUTH_CONFIG = {
@@ -74,30 +87,83 @@ type Token = {
     refresh_token: string,
 }
 
-export const BasicContext = createContext<{
-    unicorn: string,
-    isAuthReady: boolean,
-    isSignedIn: boolean,
-    user: User | null,
-    signout: () => Promise<void>,
-    signin: () => Promise<void>,
-    signinWithCode: (code: string, state?: string) => Promise<{ success: boolean, error?: string }>,
-    getToken: () => Promise<string>,
-    getSignInLink: (redirectUri?: string) => Promise<string>,
-    db: any,
-    dbStatus: DBStatus
-}>({
-    unicorn: "🦄",
-    isAuthReady: false,
+/**
+ * Auth result type for signInWithCode
+ */
+export type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+}
+
+/**
+ * Context type for useBasic hook
+ */
+export type BasicContextType = {
+    // Auth state
+    isReady: boolean;
+    isSignedIn: boolean;
+    user: User | null;
+    
+    // Auth actions (new camelCase naming)
+    signIn: () => Promise<void>;
+    signOut: () => Promise<void>;
+    signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
+    
+    // Token management
+    getToken: () => Promise<string>;
+    getSignInUrl: (redirectUri?: string) => Promise<string>;
+    
+    // DB access
+    db: BasicDB;
+    dbStatus: DBStatus;
+    dbMode: DBMode;
+    
+    // Legacy aliases (deprecated - will be removed in future version)
+    /** @deprecated Use isReady instead */
+    isAuthReady: boolean;
+    /** @deprecated Use signIn instead */
+    signin: () => Promise<void>;
+    /** @deprecated Use signOut instead */
+    signout: () => Promise<void>;
+    /** @deprecated Use signInWithCode instead */
+    signinWithCode: (code: string, state?: string) => Promise<AuthResult>;
+    /** @deprecated Use getSignInUrl instead */
+    getSignInLink: (redirectUri?: string) => Promise<string>;
+}
+
+const noDb: BasicDB = {
+    collection: () => {
+        throw new Error('no basicdb found - initialization failed. double check your schema.')
+    }
+}
+
+export const BasicContext = createContext<BasicContextType>({
+    // Auth state
+    isReady: false,
     isSignedIn: false,
     user: null,
-    signout: () => Promise.resolve(),
+    
+    // Auth actions
+    signIn: () => Promise.resolve(),
+    signOut: () => Promise.resolve(),
+    signInWithCode: () => Promise.resolve({ success: false }),
+    
+    // Token management
+    getToken: () => Promise.reject(new Error('no token')),
+    getSignInUrl: () => Promise.resolve(""),
+    
+    // DB access
+    db: noDb,
+    dbStatus: DBStatus.LOADING,
+    dbMode: 'sync',
+    
+    // Legacy aliases
+    isAuthReady: false,
     signin: () => Promise.resolve(),
-    signinWithCode: () => new Promise(() => { }),
-    getToken: () => new Promise(() => { }),
-    getSignInLink: () => Promise.resolve(""),
-    db: {},
-    dbStatus: DBStatus.LOADING
+    signout: () => Promise.resolve(),
+    signinWithCode: () => Promise.resolve({ success: false }),
+    getSignInLink: () => Promise.resolve("")
 });
 
 type ErrorObject = {
@@ -108,12 +174,16 @@ type ErrorObject = {
 
 export function BasicProvider({
     children,
-    project_id,
+    project_id: project_id_prop,
     schema,
     debug = false,
     storage,
-    auth
+    auth,
+    dbMode = 'sync'
 }: BasicProviderProps) {
+    // Extract project_id from schema, fall back to prop for backward compatibility
+    const project_id = schema?.project_id || project_id_prop
+    
     const [isAuthReady, setIsAuthReady] = useState(false)
     const [isSignedIn, setIsSignedIn] = useState<boolean>(false)
     const [token, setToken] = useState<Token | null>(null)
@@ -127,6 +197,7 @@ export function BasicProvider({
     const [pendingRefresh, setPendingRefresh] = useState<boolean>(false)
 
     const syncRef = useRef<BasicSync | null>(null);
+    const remoteDbRef = useRef<RemoteDB | null>(null);
     const storageAdapter = storage || new LocalStorageAdapter();
     
     // Merge auth config with defaults
@@ -181,19 +252,19 @@ export function BasicProvider({
     }, [pendingRefresh, token])
 
     useEffect(() => {
-        function initDb(options: { shouldConnect: boolean }) {
+        async function initSyncDb(options: { shouldConnect: boolean }) {
             if (!syncRef.current) {
-                log('Initializing Basic DB')
+                log('Initializing Basic Sync DB')
+                
+                // Initialize Dexie extensions before creating BasicSync
+                await initDexieExtensions()
+                
                 syncRef.current = new BasicSync('basicdb', { schema: schema });
 
                 syncRef.current.syncable.on('statusChanged', (status: number, url: string) => {
                     setDbStatus(getSyncStatus(status) as DBStatus)
                 })
 
-                // syncRef.current.syncable.getStatus().then((status: number) => {
-                //     setDbStatus(getSyncStatus(status) as DBStatus)
-                // })
-
                 if (options.shouldConnect) {
                     setShouldConnect(true)
                 } else {
@@ -204,6 +275,36 @@ export function BasicProvider({
             }
         }
 
+        function initRemoteDb() {
+            if (!remoteDbRef.current) {
+                if (!project_id) {
+                    setError({
+                        code: 'missing_project_id',
+                        title: 'Project ID Required',
+                        message: 'Remote mode requires a project_id. Provide it via schema.project_id or the project_id prop.'
+                    })
+                    setIsReady(true)
+                    return
+                }
+
+                log('Initializing Basic Remote DB')
+                remoteDbRef.current = new RemoteDB({
+                    serverUrl: authConfig.server_url,
+                    projectId: project_id,
+                    getToken: getToken,
+                    schema: schema,
+                    debug: debug,
+                    onAuthError: (error) => {
+                        log('RemoteDB auth error:', error)
+                        // Sign out user when authentication fails after retry
+                        signout()
+                    }
+                })
+                setDbStatus(DBStatus.ONLINE)
+                setIsReady(true)
+            }
+        }
+
         async function checkSchema() {
             const result = await validateAndCheckSchema(schema)
 
@@ -223,11 +324,17 @@ export function BasicProvider({
                 return null
             }
 
-            if (result.schemaStatus.valid) {
-                initDb({ shouldConnect: true })
+            // Initialize the appropriate DB based on mode
+            if (dbMode === 'remote') {
+                initRemoteDb()
             } else {
-                log('Schema is invalid!', result.schemaStatus)
-                initDb({ shouldConnect: false })
+                // Sync mode
+                if (result.schemaStatus.valid) {
+                    await initSyncDb({ shouldConnect: true })
+                } else {
+                    log('Schema is invalid!', result.schemaStatus)
+                    await initSyncDb({ shouldConnect: false })
+                }
             }
 
             checkForNewVersion()
@@ -236,7 +343,12 @@ export function BasicProvider({
         if (schema) {
             checkSchema()
         } else {
-            setIsReady(true)
+            // No schema - still initialize remote DB if in remote mode
+            if (dbMode === 'remote' && project_id) {
+                initRemoteDb()
+            } else {
+                setIsReady(true)
+            }
         }
     }, []);
 
@@ -829,27 +941,45 @@ export function BasicProvider({
         return refreshPromise
     }
 
-    const noDb = ({
-        collection: () => {
-            throw new Error('no basicdb found - initialization failed. double check your schema.')
+    // Get the current DB instance based on mode
+    const getCurrentDb = (): BasicDB => {
+        if (dbMode === 'remote') {
+            return remoteDbRef.current || noDb
         }
-    })
+        return syncRef.current || noDb
+    }
 
-    return (
-        <BasicContext.Provider value={{
-            unicorn: "🦄",
-            isAuthReady,
-            isSignedIn,
-            user,
-            signout,
-            signin,
-            signinWithCode,
-            getToken,
-            getSignInLink,
-            db: syncRef.current ? syncRef.current : noDb,
-            dbStatus
-        }}>
+    // Create context value with new names and legacy aliases
+    const contextValue: BasicContextType = {
+        // Auth state (new naming)
+        isReady: isAuthReady,
+        isSignedIn,
+        user,
+        
+        // Auth actions (new camelCase naming)
+        signIn: signin,
+        signOut: signout,
+        signInWithCode: signinWithCode,
+        
+        // Token management
+        getToken,
+        getSignInUrl: getSignInLink,
+        
+        // DB access
+        db: getCurrentDb(),
+        dbStatus,
+        dbMode,
+        
+        // Legacy aliases (deprecated)
+        isAuthReady,
+        signin,
+        signout,
+        signinWithCode,
+        getSignInLink,
+    }
 
+    return (
+        <BasicContext.Provider value={contextValue}>
             {error && isDevMode() && <ErrorDisplay error={error} />}
             {isReady && children}
         </BasicContext.Provider>

package/src/core/db/RemoteCollection.ts

@@ -0,0 +1,294 @@
+import { Collection, RemoteDBConfig, RemoteDBError } from './types'
+import { validateData } from '@basictech/schema'
+
+/**
+ * Error thrown when user is not authenticated
+ */
+export class NotAuthenticatedError extends Error {
+  constructor(message: string = 'Not authenticated') {
+    super(message)
+    this.name = 'NotAuthenticatedError'
+  }
+}
+
+/**
+ * RemoteCollection - REST API based implementation of the Collection interface
+ * All operations make HTTP calls to the Basic API server
+ */
+export class RemoteCollection<T extends { id: string } = Record<string, any> & { id: string }> implements Collection<T> {
+  private tableName: string
+  private config: RemoteDBConfig
+
+  constructor(tableName: string, config: RemoteDBConfig) {
+    this.tableName = tableName
+    this.config = config
+  }
+
+  private log(...args: any[]) {
+    if (this.config.debug) {
+      console.log('[RemoteDB]', ...args)
+    }
+  }
+
+  /**
+   * Check if an error is a "not authenticated" error
+   */
+  private isNotAuthenticatedError(error: unknown): boolean {
+    if (error instanceof Error) {
+      const message = error.message.toLowerCase()
+      return message.includes('no token') || 
+             message.includes('not authenticated') ||
+             message.includes('please sign in')
+    }
+    return false
+  }
+
+  /**
+   * Helper to make authenticated API requests
+   * Automatically retries once on 401 (token expired) by refreshing the token
+   */
+  private async request<R>(
+    method: string,
+    path: string,
+    body?: any,
+    isRetry: boolean = false
+  ): Promise<R> {
+    // Try to get token - may throw if not authenticated
+    const token = await this.config.getToken()
+    const url = `${this.config.serverUrl}${path}`
+
+    this.log(`${method} ${url}`, body ? JSON.stringify(body) : '')
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`
+      },
+      ...(body ? { body: JSON.stringify(body) } : {})
+    })
+
+    const responseData = await response.json().catch(() => ({}))
+
+    if (!response.ok) {
+      // Handle 401 Unauthorized - token may have expired
+      if (response.status === 401 && !isRetry) {
+        this.log('Got 401, retrying with fresh token...')
+        // getToken() should refresh the token if expired
+        // Retry the request once
+        return this.request<R>(method, path, body, true)
+      }
+
+      if (this.config.debug) {
+        console.error(`[RemoteDB] Error ${response.status}:`, responseData)
+      }
+      
+      // Call onAuthError callback if provided and this is an auth error
+      if (response.status === 401 && this.config.onAuthError) {
+        this.config.onAuthError({
+          status: response.status,
+          message: 'Authentication failed',
+          response: responseData
+        })
+      }
+
+      // Try different error message fields that APIs commonly use
+      const errorMessage = responseData.message || responseData.error || responseData.detail || 
+        (typeof responseData === 'string' ? responseData : `API request failed: ${response.status}`)
+      throw new RemoteDBError(errorMessage, response.status, responseData)
+    }
+
+    this.log('Response:', responseData)
+    return responseData
+  }
+
+  /**
+   * Validate data against schema if available
+   */
+  private validateData(data: any, checkRequired: boolean = true): void {
+    if (this.config.schema) {
+      const result = validateData(this.config.schema, this.tableName, data, checkRequired)
+      if (!result.valid) {
+        throw new Error(result.message || 'Data validation failed')
+      }
+    }
+  }
+
+  /**
+   * Get the base path for this collection
+   */
+  private get basePath(): string {
+    return `/account/${this.config.projectId}/db/${this.tableName}`
+  }
+
+  /**
+   * Add a new record to the collection
+   * The server generates the ID
+   * Requires authentication - throws NotAuthenticatedError if not signed in
+   */
+  async add(data: Omit<T, 'id'>): Promise<T> {
+    this.validateData(data, true)
+
+    try {
+      const result = await this.request<{ data: T }>(
+        'POST',
+        this.basePath,
+        { value: data }
+      )
+      // Server returns the created record with the generated ID
+      return result.data
+    } catch (error) {
+      if (this.isNotAuthenticatedError(error)) {
+        throw new NotAuthenticatedError('Sign in required to add items')
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Put (upsert) a record - requires id
+   * Requires authentication - throws NotAuthenticatedError if not signed in
+   */
+  async put(data: T): Promise<T> {
+    if (!data.id) {
+      throw new Error('put() requires an id field')
+    }
+
+    // Extract id from data, send the rest in the body
+    const { id, ...rest } = data
+    this.validateData(rest, true)
+
+    try {
+      const result = await this.request<{ data: T }>(
+        'PUT',
+        `${this.basePath}/${id}`,
+        { value: rest }
+      )
+      return result.data || data
+    } catch (error) {
+      if (this.isNotAuthenticatedError(error)) {
+        throw new NotAuthenticatedError('Sign in required to update items')
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Update an existing record by id
+   * Requires authentication - throws NotAuthenticatedError if not signed in
+   */
+  async update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null> {
+    if (!id) {
+      throw new Error('update() requires an id')
+    }
+
+    this.validateData(data, false)
+
+    try {
+      const result = await this.request<{ data: T }>(
+        'PATCH',
+        `${this.basePath}/${id}`,
+        { value: data }
+      )
+
+      return result.data || null
+    } catch (error) {
+      // If record not found, return null instead of throwing
+      if (error instanceof RemoteDBError && error.status === 404) {
+        return null
+      }
+      if (this.isNotAuthenticatedError(error)) {
+        throw new NotAuthenticatedError('Sign in required to update items')
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Delete a record by id
+   * Requires authentication - throws NotAuthenticatedError if not signed in
+   */
+  async delete(id: string): Promise<boolean> {
+    if (!id) {
+      throw new Error('delete() requires an id')
+    }
+
+    try {
+      await this.request<any>(
+        'DELETE',
+        `${this.basePath}/${id}`
+      )
+      return true
+    } catch (error) {
+      // If record not found, return false instead of throwing
+      if (error instanceof RemoteDBError && error.status === 404) {
+        return false
+      }
+      if (this.isNotAuthenticatedError(error)) {
+        throw new NotAuthenticatedError('Sign in required to delete items')
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Get a single record by id
+   * Returns null if not authenticated (graceful degradation for read operations)
+   */
+  async get(id: string): Promise<T | null> {
+    if (!id) {
+      throw new Error('get() requires an id')
+    }
+
+    try {
+      // Use the API's id query parameter for efficient single-record fetch
+      const result = await this.request<{ data: T[] }>(
+        'GET',
+        `${this.basePath}?id=${id}`
+      )
+      return result.data?.[0] || null
+    } catch (error) {
+      // For get(), return null on any error (not found, not authenticated, etc.)
+      if (this.isNotAuthenticatedError(error)) {
+        this.log('Not authenticated - returning null for get()')
+      }
+      return null
+    }
+  }
+
+  /**
+   * Get all records in the collection
+   * Returns empty array if not authenticated (graceful degradation for read operations)
+   */
+  async getAll(): Promise<T[]> {
+    try {
+      const result = await this.request<{ data: T[] }>(
+        'GET',
+        this.basePath
+      )
+      return result.data || []
+    } catch (error) {
+      // If not authenticated, return empty array gracefully
+      if (this.isNotAuthenticatedError(error)) {
+        this.log('Not authenticated - returning empty array for getAll()')
+        return []
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Filter records using a predicate function
+   * Note: This fetches all records and filters client-side
+   * Returns empty array if not authenticated (graceful degradation for read operations)
+   */
+  async filter(fn: (item: T) => boolean): Promise<T[]> {
+    const all = await this.getAll()
+    return all.filter(fn)
+  }
+
+  /**
+   * ref is not available for remote collections
+   */
+  ref = undefined
+}

package/src/core/db/RemoteDB.ts

@@ -0,0 +1,40 @@
+import { BasicDB, Collection, RemoteDBConfig } from './types'
+import { RemoteCollection } from './RemoteCollection'
+
+/**
+ * RemoteDB - REST API based implementation of BasicDB
+ * Creates RemoteCollection instances for each table
+ */
+export class RemoteDB implements BasicDB {
+  private config: RemoteDBConfig
+  private collections: Map<string, RemoteCollection<any>> = new Map()
+
+  constructor(config: RemoteDBConfig) {
+    this.config = config
+  }
+
+  /**
+   * Get a collection by name
+   * Collections are cached for reuse
+   */
+  collection<T extends { id: string } = Record<string, any> & { id: string }>(
+    name: string
+  ): Collection<T> {
+    // Return cached collection if exists
+    if (this.collections.has(name)) {
+      return this.collections.get(name) as RemoteCollection<T>
+    }
+
+    // Validate table exists in schema if schema is provided
+    if (this.config.schema?.tables && !this.config.schema.tables[name]) {
+      throw new Error(`Table "${name}" not found in schema`)
+    }
+
+    // Create and cache new collection
+    const collection = new RemoteCollection<T>(name, this.config)
+    this.collections.set(name, collection)
+
+    return collection
+  }
+}
+

package/src/core/db/index.ts

@@ -0,0 +1,7 @@
+// Core DB exports
+export type { Collection, BasicDB, DBMode, RemoteDBConfig } from './types'
+export type { AuthError } from './types'
+export { RemoteDBError } from './types'
+export { RemoteDB } from './RemoteDB'
+export { RemoteCollection, NotAuthenticatedError } from './RemoteCollection'
+