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

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @basictech/react@0.7.0-beta.3 build
+> @basictech/react@0.7.0-beta.6 build
 > tsup
 
 CLI Building entry: src/index.ts
@@ -11,13 +11,13 @@
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-CJS dist/index.js     41.20 KB
-CJS dist/index.js.map 82.45 KB
-CJS ⚡️ Build success in 17ms
-ESM dist/index.mjs     39.45 KB
-ESM dist/index.mjs.map 82.44 KB
-ESM ⚡️ Build success in 18ms
+ESM dist/index.mjs     55.69 KB
+ESM dist/index.mjs.map 116.91 KB
+ESM ⚡️ Build success in 21ms
+CJS dist/index.js     57.98 KB
+CJS dist/index.js.map 116.96 KB
+CJS ⚡️ Build success in 21ms
 DTS Build start
-DTS ⚡️ Build success in 905ms
-DTS dist/index.d.ts  1.76 KB
-DTS dist/index.d.mts 1.76 KB
+DTS ⚡️ Build success in 1353ms
+DTS dist/index.d.ts  9.48 KB
+DTS dist/index.d.mts 9.48 KB

package/changelog.md

@@ -1,5 +1,11 @@
 # 1.3.4
 
+## 0.7.0-beta.7
+
+### Minor Changes
+
+- api improvements, react refactor, nextjs update
+
 ## 0.7.0-beta.6
 
 ### Patch Changes

package/dist/index.d.mts

@@ -2,6 +2,221 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 export { useLiveQuery as useQuery } from 'dexie-react-hooks';
 
+/**
+ * Core DB types for Basic SDK
+ * These interfaces are implemented by both SyncDB (Dexie-based) and RemoteDB (REST-based)
+ */
+/**
+ * Collection interface for CRUD operations on a table
+ * All write operations return the full object (not just the id)
+ */
+interface Collection<T extends {
+    id: string;
+} = Record<string, any> & {
+    id: string;
+}> {
+    /**
+     * Add a new record to the collection
+     * @param data - The data to add (without id, which will be generated)
+     * @returns The created object with its generated id
+     */
+    add(data: Omit<T, 'id'>): Promise<T>;
+    /**
+     * Put (upsert) a record - requires id
+     * @param data - The full object including id
+     * @returns The upserted object
+     */
+    put(data: T): Promise<T>;
+    /**
+     * Update an existing record by id
+     * @param id - The record id to update
+     * @param data - Partial data to merge
+     * @returns The updated object, or null if not found
+     */
+    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    /**
+     * Delete a record by id
+     * @param id - The record id to delete
+     * @returns true if deleted, false if not found
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Get a single record by id
+     * @param id - The record id to fetch
+     * @returns The object or null if not found
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * Get all records in the collection
+     * @returns Array of all objects
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Filter records using a predicate function
+     * @param fn - Filter function that returns true for matches
+     * @returns Array of matching objects
+     */
+    filter(fn: (item: T) => boolean): Promise<T[]>;
+    /**
+     * Direct access to underlying storage (optional)
+     * For sync mode: Dexie table reference
+     * For remote mode: undefined
+     */
+    ref?: any;
+}
+/**
+ * BasicDB interface - factory for creating collections
+ */
+interface BasicDB {
+    /**
+     * Get a collection by name
+     * @param name - The table/collection name (must match schema)
+     * @returns A Collection instance for CRUD operations
+     */
+    collection<T extends {
+        id: string;
+    } = Record<string, any> & {
+        id: string;
+    }>(name: string): Collection<T>;
+}
+/**
+ * Database mode - determines which implementation is used
+ * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
+ * - 'remote': Uses REST API calls directly to server
+ */
+type DBMode = 'sync' | 'remote';
+/**
+ * Auth error information passed to onAuthError callback
+ */
+interface AuthError {
+    status: number;
+    message: string;
+    response?: any;
+}
+/**
+ * Custom error class for Remote DB API errors
+ * Includes HTTP status code for reliable error handling
+ */
+declare class RemoteDBError extends Error {
+    status: number;
+    response?: any;
+    constructor(message: string, status: number, response?: any);
+}
+/**
+ * Configuration for RemoteDB
+ */
+interface RemoteDBConfig {
+    serverUrl: string;
+    projectId: string;
+    getToken: () => Promise<string>;
+    schema?: any;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /**
+     * Optional callback when authentication fails (401 error after retry)
+     * Use this to show login UI or redirect to sign-in
+     */
+    onAuthError?: (error: AuthError) => void;
+}
+
+/**
+ * RemoteDB - REST API based implementation of BasicDB
+ * Creates RemoteCollection instances for each table
+ */
+declare class RemoteDB implements BasicDB {
+    private config;
+    private collections;
+    constructor(config: RemoteDBConfig);
+    /**
+     * Get a collection by name
+     * Collections are cached for reuse
+     */
+    collection<T extends {
+        id: string;
+    } = Record<string, any> & {
+        id: string;
+    }>(name: string): Collection<T>;
+}
+
+/**
+ * Error thrown when user is not authenticated
+ */
+declare class NotAuthenticatedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * RemoteCollection - REST API based implementation of the Collection interface
+ * All operations make HTTP calls to the Basic API server
+ */
+declare class RemoteCollection<T extends {
+    id: string;
+} = Record<string, any> & {
+    id: string;
+}> implements Collection<T> {
+    private tableName;
+    private config;
+    constructor(tableName: string, config: RemoteDBConfig);
+    private log;
+    /**
+     * Check if an error is a "not authenticated" error
+     */
+    private isNotAuthenticatedError;
+    /**
+     * Helper to make authenticated API requests
+     * Automatically retries once on 401 (token expired) by refreshing the token
+     */
+    private request;
+    /**
+     * Validate data against schema if available
+     */
+    private validateData;
+    /**
+     * Get the base path for this collection
+     */
+    private get basePath();
+    /**
+     * Add a new record to the collection
+     * The server generates the ID
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    add(data: Omit<T, 'id'>): Promise<T>;
+    /**
+     * Put (upsert) a record - requires id
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    put(data: T): Promise<T>;
+    /**
+     * Update an existing record by id
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    /**
+     * Delete a record by id
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Get a single record by id
+     * Returns null if not authenticated (graceful degradation for read operations)
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * Get all records in the collection
+     * Returns empty array if not authenticated (graceful degradation for read operations)
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * 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)
+     */
+    filter(fn: (item: T) => boolean): Promise<T[]>;
+    /**
+     * ref is not available for remote collections
+     */
+    ref: undefined;
+}
+
 interface BasicStorage {
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;
@@ -12,6 +227,14 @@ declare class LocalStorageAdapter implements BasicStorage {
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
 }
+declare const STORAGE_KEYS: {
+    readonly REFRESH_TOKEN: "basic_refresh_token";
+    readonly USER_INFO: "basic_user_info";
+    readonly AUTH_STATE: "basic_auth_state";
+    readonly REDIRECT_URI: "basic_redirect_uri";
+    readonly SERVER_URL: "basic_server_url";
+    readonly DEBUG: "basic_debug";
+};
 
 type AuthConfig = {
     scopes?: string | string[];
@@ -20,11 +243,22 @@ type AuthConfig = {
 };
 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;
 };
 declare enum DBStatus {
     LOADING = "LOADING",
@@ -43,22 +277,41 @@ type User = {
     };
     fullName?: string;
 };
-declare function BasicProvider({ children, project_id, schema, debug, storage, auth }: BasicProviderProps): react_jsx_runtime.JSX.Element;
-declare function useBasic(): {
-    unicorn: string;
-    isAuthReady: boolean;
+/**
+ * Auth result type for signInWithCode
+ */
+type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+};
+/**
+ * Context type for useBasic hook
+ */
+type BasicContextType = {
+    isReady: boolean;
     isSignedIn: boolean;
     user: User | null;
-    signout: () => Promise<void>;
-    signin: () => Promise<void>;
-    signinWithCode: (code: string, state?: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    signIn: () => Promise<void>;
+    signOut: () => Promise<void>;
+    signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
     getToken: () => Promise<string>;
-    getSignInLink: (redirectUri?: string) => Promise<string>;
-    db: any;
+    getSignInUrl: (redirectUri?: string) => Promise<string>;
+    db: BasicDB;
     dbStatus: DBStatus;
+    dbMode: DBMode;
+    /** @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>;
 };
+declare function BasicProvider({ children, project_id: project_id_prop, schema, debug, storage, auth, dbMode }: BasicProviderProps): react_jsx_runtime.JSX.Element;
+declare function useBasic(): BasicContextType;
 
-export { AuthConfig, BasicProvider, BasicProviderProps, BasicStorage, LocalStorageAdapter, useBasic };
+export { AuthConfig, AuthError, AuthResult, BasicContextType, BasicDB, BasicProvider, BasicProviderProps, BasicStorage, Collection, DBMode, LocalStorageAdapter, NotAuthenticatedError, RemoteCollection, RemoteDB, RemoteDBConfig, RemoteDBError, STORAGE_KEYS, useBasic };

package/dist/index.d.ts

@@ -2,6 +2,221 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 export { useLiveQuery as useQuery } from 'dexie-react-hooks';
 
+/**
+ * Core DB types for Basic SDK
+ * These interfaces are implemented by both SyncDB (Dexie-based) and RemoteDB (REST-based)
+ */
+/**
+ * Collection interface for CRUD operations on a table
+ * All write operations return the full object (not just the id)
+ */
+interface Collection<T extends {
+    id: string;
+} = Record<string, any> & {
+    id: string;
+}> {
+    /**
+     * Add a new record to the collection
+     * @param data - The data to add (without id, which will be generated)
+     * @returns The created object with its generated id
+     */
+    add(data: Omit<T, 'id'>): Promise<T>;
+    /**
+     * Put (upsert) a record - requires id
+     * @param data - The full object including id
+     * @returns The upserted object
+     */
+    put(data: T): Promise<T>;
+    /**
+     * Update an existing record by id
+     * @param id - The record id to update
+     * @param data - Partial data to merge
+     * @returns The updated object, or null if not found
+     */
+    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    /**
+     * Delete a record by id
+     * @param id - The record id to delete
+     * @returns true if deleted, false if not found
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Get a single record by id
+     * @param id - The record id to fetch
+     * @returns The object or null if not found
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * Get all records in the collection
+     * @returns Array of all objects
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Filter records using a predicate function
+     * @param fn - Filter function that returns true for matches
+     * @returns Array of matching objects
+     */
+    filter(fn: (item: T) => boolean): Promise<T[]>;
+    /**
+     * Direct access to underlying storage (optional)
+     * For sync mode: Dexie table reference
+     * For remote mode: undefined
+     */
+    ref?: any;
+}
+/**
+ * BasicDB interface - factory for creating collections
+ */
+interface BasicDB {
+    /**
+     * Get a collection by name
+     * @param name - The table/collection name (must match schema)
+     * @returns A Collection instance for CRUD operations
+     */
+    collection<T extends {
+        id: string;
+    } = Record<string, any> & {
+        id: string;
+    }>(name: string): Collection<T>;
+}
+/**
+ * Database mode - determines which implementation is used
+ * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
+ * - 'remote': Uses REST API calls directly to server
+ */
+type DBMode = 'sync' | 'remote';
+/**
+ * Auth error information passed to onAuthError callback
+ */
+interface AuthError {
+    status: number;
+    message: string;
+    response?: any;
+}
+/**
+ * Custom error class for Remote DB API errors
+ * Includes HTTP status code for reliable error handling
+ */
+declare class RemoteDBError extends Error {
+    status: number;
+    response?: any;
+    constructor(message: string, status: number, response?: any);
+}
+/**
+ * Configuration for RemoteDB
+ */
+interface RemoteDBConfig {
+    serverUrl: string;
+    projectId: string;
+    getToken: () => Promise<string>;
+    schema?: any;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /**
+     * Optional callback when authentication fails (401 error after retry)
+     * Use this to show login UI or redirect to sign-in
+     */
+    onAuthError?: (error: AuthError) => void;
+}
+
+/**
+ * RemoteDB - REST API based implementation of BasicDB
+ * Creates RemoteCollection instances for each table
+ */
+declare class RemoteDB implements BasicDB {
+    private config;
+    private collections;
+    constructor(config: RemoteDBConfig);
+    /**
+     * Get a collection by name
+     * Collections are cached for reuse
+     */
+    collection<T extends {
+        id: string;
+    } = Record<string, any> & {
+        id: string;
+    }>(name: string): Collection<T>;
+}
+
+/**
+ * Error thrown when user is not authenticated
+ */
+declare class NotAuthenticatedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * RemoteCollection - REST API based implementation of the Collection interface
+ * All operations make HTTP calls to the Basic API server
+ */
+declare class RemoteCollection<T extends {
+    id: string;
+} = Record<string, any> & {
+    id: string;
+}> implements Collection<T> {
+    private tableName;
+    private config;
+    constructor(tableName: string, config: RemoteDBConfig);
+    private log;
+    /**
+     * Check if an error is a "not authenticated" error
+     */
+    private isNotAuthenticatedError;
+    /**
+     * Helper to make authenticated API requests
+     * Automatically retries once on 401 (token expired) by refreshing the token
+     */
+    private request;
+    /**
+     * Validate data against schema if available
+     */
+    private validateData;
+    /**
+     * Get the base path for this collection
+     */
+    private get basePath();
+    /**
+     * Add a new record to the collection
+     * The server generates the ID
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    add(data: Omit<T, 'id'>): Promise<T>;
+    /**
+     * Put (upsert) a record - requires id
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    put(data: T): Promise<T>;
+    /**
+     * Update an existing record by id
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    /**
+     * Delete a record by id
+     * Requires authentication - throws NotAuthenticatedError if not signed in
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Get a single record by id
+     * Returns null if not authenticated (graceful degradation for read operations)
+     */
+    get(id: string): Promise<T | null>;
+    /**
+     * Get all records in the collection
+     * Returns empty array if not authenticated (graceful degradation for read operations)
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * 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)
+     */
+    filter(fn: (item: T) => boolean): Promise<T[]>;
+    /**
+     * ref is not available for remote collections
+     */
+    ref: undefined;
+}
+
 interface BasicStorage {
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;
@@ -12,6 +227,14 @@ declare class LocalStorageAdapter implements BasicStorage {
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
 }
+declare const STORAGE_KEYS: {
+    readonly REFRESH_TOKEN: "basic_refresh_token";
+    readonly USER_INFO: "basic_user_info";
+    readonly AUTH_STATE: "basic_auth_state";
+    readonly REDIRECT_URI: "basic_redirect_uri";
+    readonly SERVER_URL: "basic_server_url";
+    readonly DEBUG: "basic_debug";
+};
 
 type AuthConfig = {
     scopes?: string | string[];
@@ -20,11 +243,22 @@ type AuthConfig = {
 };
 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;
 };
 declare enum DBStatus {
     LOADING = "LOADING",
@@ -43,22 +277,41 @@ type User = {
     };
     fullName?: string;
 };
-declare function BasicProvider({ children, project_id, schema, debug, storage, auth }: BasicProviderProps): react_jsx_runtime.JSX.Element;
-declare function useBasic(): {
-    unicorn: string;
-    isAuthReady: boolean;
+/**
+ * Auth result type for signInWithCode
+ */
+type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+};
+/**
+ * Context type for useBasic hook
+ */
+type BasicContextType = {
+    isReady: boolean;
     isSignedIn: boolean;
     user: User | null;
-    signout: () => Promise<void>;
-    signin: () => Promise<void>;
-    signinWithCode: (code: string, state?: string) => Promise<{
-        success: boolean;
-        error?: string;
-    }>;
+    signIn: () => Promise<void>;
+    signOut: () => Promise<void>;
+    signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
     getToken: () => Promise<string>;
-    getSignInLink: (redirectUri?: string) => Promise<string>;
-    db: any;
+    getSignInUrl: (redirectUri?: string) => Promise<string>;
+    db: BasicDB;
     dbStatus: DBStatus;
+    dbMode: DBMode;
+    /** @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>;
 };
+declare function BasicProvider({ children, project_id: project_id_prop, schema, debug, storage, auth, dbMode }: BasicProviderProps): react_jsx_runtime.JSX.Element;
+declare function useBasic(): BasicContextType;
 
-export { AuthConfig, BasicProvider, BasicProviderProps, BasicStorage, LocalStorageAdapter, useBasic };
+export { AuthConfig, AuthError, AuthResult, BasicContextType, BasicDB, BasicProvider, BasicProviderProps, BasicStorage, Collection, DBMode, LocalStorageAdapter, NotAuthenticatedError, RemoteCollection, RemoteDB, RemoteDBConfig, RemoteDBError, STORAGE_KEYS, useBasic };