asasvirtuais 0.4.4 → 0.5.0

package/README.md

@@ -1,222 +1,421 @@
-
-1st: Declare your database schema
-```ts
-import { z } from 'zod'
-export const schema = {
-    users: {
-        readable: {
-            id: z.string(),
-            name: z.string(),
-            email: z.string().email(),
-        },
-        writable: {
-            name: z.string(),
-            email: z.string().email(),
-        }
-    }
-}
-```
-
-2nd: Write your adapters (or use existing ones)
-```ts
-import { tableInterface } from 'asasvirtuais/interface'
-const myDatabaseAdapter = tableInterface(
-    schema,
-    null, // Null for generic interface,
-    { 
-        find(props) {...},
-        list(props) {...},
-        create(props) {...},
-        update(props) {...},
-        delete(props) {...},
-    }
-)
-myDatabaseAdapter.create({table: '', data: {...}})
-const myTableAdapter = tableInterface(schema, 'table', {...})
-myTableAdapter.create({data: {...}})
-```
-
-3rd: expose the API endpoints
-```ts
-import { myDatabaseAdapter } from './adapter'
-import { createDynamicRoute } from 'asasvirtuais/next-interface'
-export const GET = createDynamicRoute(myDatabaseAdapter)
-export const POST = createDynamicRoute(myDatabaseAdapter)
-export const PATCH = createDynamicRoute(myDatabaseAdapter)
-export const DELETE = createDynamicRoute(myDatabaseAdapter)
-```
-
-4th: consume the RESTful API
-```ts
-'use client'
-import { fetchInterface } from '@/packages/fetch-interface'
-import { schema } from './database'
-import { database } from '@/packages/react-interface'
-
-const fethcher = fetchInterface({schema, baseURL: 'http://localhost:3000/api/v1', headers: {} })
-const { find, list, create, update, remove } = fetcher
-
-// Super useful
-export const { DatabaseProvider, useDatabase, useTable, CreateForm, UpdateForm, FilterForm, SingleProvider, useSingle } = database<typeof schema>(schema, fetcher)
-```
-
-5th: Using the DatabaseProvider
-```tsx
-// You are required to write all the table names you'll use beneath this context provider
-<DatabaseProvider users={index} chats={{[id]: chat}} messages={{}}>
-    {...}
-</DatabaseProvider>
-```
-
-6th: Provide and consume the context
-```tsx
-// CreateForm, UpdateForm and FiltersForm use asasvirtuais/form and asasvirtuais/fields
-<CreateForm table='table' onSuccess={handleResult}>
-    {/* Note: callback accepts the props of the method (list, create, update) */}
-    {({loading, result, error, submit, callback}) => {
-        return (
-            <form onSubmit={submit}>
-                <FiltersFields/>
-                <SubmitButton disabled={loading} loading={loading}>
-                    {loading ? <Spinner/> : 'Apply Filters'}
-                </SubmitButton>
-                {result.map(item => <ViewItem key={item.id} item={item} />)}
-            </form>
-        )
-    }}
-</CreateForm>
-
-// To avoid prop drilling of data models
-<SingleProvider table='users' id={id}>
-{
-    const { single: user } = useSingle()
-}
-</SingleProvider>
-```
-
-7th: Use our fields on your form
-```tsx
-import { fields } from 'asasvirtuais-fields'
-<CreateForm table='table' defaults={{belongsTo: user.id}}>
-    {(props) => (
-        <Stack>
-            <fields.string.Edit value={props.fields.name} setValue={value => props.setField('name', value)} />
-            <Button type='submit' loading={props.loading}>
-        </Stack>
-    )}
-</CreateForm>
-```
-
-Querying the database
-```ts
-const array = await myTableAdapter.list({query: { id }})
-```
-
-Form and Fields packages
-```tsx
-import { FormProvider } from 'asasvirtuais/form'
-import { FieldsProvider } from 'asasvirtuais/fields'
-<FormProvider<Props, Result> data={FormDataOrObject} onSuccess={handleResult}>
-    {({error, result, loading, values, submit, callback}) => {
-        return (
-            <FieldsProvider<{key: value}> defaults={[propKey]: propValue}>
-                {({field, setField, setFields}) => (
-                    <SomeFieldComponent value={field} onChange={value => setField(value)} />
-                )}
-            </FieldsProvider>
-        )
-    }}
-</FormProvider>
-```
-
-Effects Example
-```ts
-import { authenticate } from '@/packages/auth0'
-import { createDynamicRoute } from '@/packages/next-interface'
-import { firestoreInterface } from '@/packages/firestore'
-
-const dbInterface = firestoreInterface()
-
-const apiInterface = {
-    async create(props) {
-        await authenticate()
-        return dbInterface.create(props)
-    },
-    async find(props) {
-        await authenticate()
-        return dbInterface.find(props)
-    },
-    async update(props) {
-        await authenticate()
-        return dbInterface.update(props)
-    },
-    async remove(props) {
-        await authenticate()
-        return dbInterface.remove(props)
-    },
-    async list(props) {
-        await authenticate()
-        return dbInterface.list(props)
-    },
-} as typeof dbInterface
-```
-
-Forms Example
-```tsx
-<UpdateForm table='characters' id={characterId} defaults={{
-    name: character.name,
-    avatar: (character).avatar ?? '',
-    personality: character.personality,
-    appearance: character.appearance,
-    definition: character.definition,
-}} onSuccess={(character) => addCharacterToChat(character)}>
-    {(props) => (
-        <Stack asChild>
-            <form onSubmit={props.submit}>
-                <Stack gap={3}>
-                    <div>
-                        <Text>Name</Text>
-                        <Input value={(props.fields).name ?? ''} onChange={e => props.setField('name', e.target.value)} />
-                    </div>
-                    <div>
-                        <Text>Avatar</Text>
-                        <AvatarUpload value={(props.fields).avatar ?? ''} onChange={(url: string) => props.setField('avatar' , url)} />
-                    </div>
-                    <div>
-                        <Text>Personality</Text>
-                        <Textarea value={(props.fields).personality ?? ''} onChange={e => props.setField('personality', e.target.value)} />
-                    </div>
-                    <div>
-                        <Text>Appearance</Text>
-                        <Textarea value={(props.fields).appearance ?? ''} onChange={e => props.setField('appearance', e.target.value)} />
-                    </div>
-                    <div>
-                        <Text>Definition</Text>
-                        <Textarea value={(props.fields).definition ?? ''} onChange={e => props.setField('definition', e.target.value)} />
-                    </div>
-                    <HStack justify='flex-end' gap={2}>
-                        <Button type='button' size='sm' variant='outline' colorPalette='red' disabled={remove.loading} onClick={handleDelete}>
-                            {remove.loading ? <Spinner size='sm' /> : 'Delete'}
-                        </Button>
-                        <Button type='submit' size='sm' disabled={props.loading}>
-                            {props.loading ? <Spinner size='sm' /> : 'Save'}
-                        </Button>
-                    </HStack>
-                </Stack>
-            </form>
-        </Stack>
-    )}
-</UpdateForm>
-```
-
-Roadmap:
- - Relationships, linked records, TableLookup field
- - Realtime database with feathersjs
-
-
-TODO, add this to github actions and set the secret for this cron job authorization
-    "path": "/api/cron/diary-greeting"
-    "schedule": "*/5 * * * *"
-    "path": "/api/cron/diary-summarize"
-    "schedule": "55 23 * * *"
-
+# Asas Virtuais Framework
+
+Asas Virtuais is a full-stack, schema-driven framework for Next.js designed for rapid, type-safe, and maintainable application development. It provides a powerful abstraction layer for data management, allowing you to define your data shape once with Zod and get automatically generated API endpoints, client-side hooks, and form components.
+
+## Core Principles
+
+- **Schema First**: Define your data models using Zod schemas. This provides a single source of truth for validation, type safety, and data shape across the entire stack.
+- **Interface-Driven**: Code against a standardized `TableInterface` on both the client and server. This decouples your application logic from the specific database implementation, allowing for easy swapping of backends.
+- **Convention over Configuration**: The framework automatically generates RESTful API endpoints and client-side hooks from your schema, minimizing boilerplate and accelerating development.
+- **Extensible by Design**: Every layer is built to be wrapped or replaced. You can easily add custom logic like authentication to API endpoints, create new database adapters, or build bespoke form field components.
+
+## Step-by-Step Guide
+
+This guide will walk you through building a feature using the Asas Virtuais framework.
+
+### Step 1: Define Your Schema
+
+Everything starts with your data schema. Use Zod to define `readable` (data sent to the client) and `writable` (data accepted from the client) shapes for each table.
+
+`app/database.ts`:
+```ts
+import { z } from 'zod'
+
+export const schema = {
+    // A generic 'users' table
+    users: {
+        readable: z.object({
+            id: z.string(),
+            name: z.string(),
+            email: z.string().email(),
+        }),
+        writable: z.object({
+            name: z.string().nonempty('Name is required'),
+            email: z.string().email(),
+        })
+    },
+    // A generic 'posts' table
+    posts: {
+        readable: z.object({
+            id: z.string(),
+            title: z.string(),
+            content: z.string().optional(),
+            authorId: z.string(),
+        }),
+        writable: z.object({
+            title: z.string().nonempty('Title is required'),
+            content: z.string().optional(),
+            authorId: z.string(),
+        })
+    },
+}
+```
+
+### Step 2: Create a Server-Side Adapter
+
+Implement the `TableInterface` for your chosen database. The framework is backend-agnostic. This project uses a Firestore adapter.
+
+`packages/firestore.ts`:
+```ts
+import { TableInterface } from './interface'
+import { firestore } from './firebase'
+
+// A generic Firestore adapter implementing the standard interface
+export function firestoreInterface<...>(defaultTable?: T): TableInterface<...> {
+  return {
+    async find({ table = defaultTable, id }) {
+      const docSnap = await firestore.collection(table).doc(id).get()
+      if (docSnap.exists) return { id: docSnap.id, ...docSnap.data() }
+      throw new Error(`Record not found`)
+    },
+    // ... list, create, update, remove implementations
+  }
+}
+```
+
+Then, instantiate the adapter for each of your tables.
+
+`app/server.ts`:
+```ts
+import { firestoreInterface } from '@/packages/firestore'
+import { schema } from './database'
+
+// Create a server-side data access object
+export const server = {
+    users: firestoreInterface<typeof schema, 'users'>('users'),
+    posts: firestoreInterface<typeof schema, 'posts'>('posts'),
+}
+```
+
+### Step 3: Expose API Endpoints
+
+With the server adapter ready, you can expose it as a RESTful API using `createDynamicRoute`. This automatically creates `GET`, `POST`, `PATCH`, and `DELETE` handlers. You can easily wrap the base implementation to add cross-cutting concerns like authentication.
+
+`app/api/v1/[...params]/route.ts`:
+```ts
+import { authenticate } from '@/packages/auth0' // Your authentication logic
+import { createDynamicRoute } from '@/packages/next-interface'
+import { firestoreInterface } from '@/packages/firestore'
+
+const dbInterface = firestoreInterface()
+
+// Wrap the base interface to enforce business logic and authentication
+const apiInterface = {
+    async create(props) {
+        const user = await authenticate()
+        // Example: Inject the authorId automatically
+        if (props.table === 'posts') {
+            props.data.authorId = user.id 
+        }
+        return dbInterface.create(props)
+    },
+    async find(props) {
+        const user = await authenticate()
+        const result = await dbInterface.find(props)
+        // Example: Check for ownership on 'posts'
+        if (result.authorId && result.authorId !== user.id) {
+            throw new Error('Unauthorized')
+        }
+        return result
+    },
+    // ... implementations for update, remove, and list with auth checks
+} as typeof dbInterface
+
+// Export the dynamic route handlers
+export const GET = createDynamicRoute(apiInterface)
+export const POST = createDynamicRoute(apiInterface)
+export const DELETE = createDynamicRoute(apiInterface)
+export const PATCH = createDynamicRoute(apiInterface)
+```
+
+### Step 4: Initialize the Client Interface
+
+On the client, initialize the React interface. This will provide all the hooks and components you need to interact with your API.
+
+`app/interface.tsx`:
+```tsx
+'use client'
+import { fetchInterface } from '@/packages/fetch-interface'
+import { schema } from './database'
+import { reactInterface } from '@/packages/react-interface'
+
+// Create the client-side fetcher
+const fetcher = fetchInterface({ schema, baseUrl: '/api/v1' })
+
+// Export all the React hooks and components for the app
+export const { 
+    DatabaseProvider, 
+    useTable, 
+    CreateForm, 
+    UpdateForm, 
+    SingleProvider, 
+    useSingle,
+    // ... and more
+} = reactInterface<typeof schema>(schema, fetcher)
+```
+
+### Step 5: Provide Data with `DatabaseProvider`
+
+In your layouts, use `DatabaseProvider` to fetch initial data and make it available to all components underneath it via React Context.
+
+`app/posts/[id]/layout.tsx`:
+```tsx
+import { DatabaseProvider, SingleProvider } from '@/app/interface'
+import { server } from '@/app/server'
+import { layout } from '@/packages/next'
+
+export default layout<{ id: string }>( async ({ id, children }) => {
+    // Fetch initial data on the server
+    const post = await server.posts.find({ id })
+
+    // Provide the fetched data to the client-side context
+    return (
+        <DatabaseProvider posts={{ [id]: post }} users={{}}>
+            <SingleProvider id={id} table='posts'>
+                {children}
+            </SingleProvider>
+        </DatabaseProvider>
+    )
+} )
+```
+
+### Step 6: Consume Data with Hooks
+
+Use the provided hooks to access and manipulate data in your components.
+
+#### `useTable`
+To work with a collection of records (list, create, update, delete).
+
+`app/posts/page.tsx`:
+```tsx
+'use client'
+import { useTable } from '@/app/interface'
+import Link from 'next/link'
+import { IconButton } from '@chakra-ui/react'
+import { LuTrash } from 'react-icons/lu'
+
+export default function PostsPage() {
+    const { array: posts, remove, list } = useTable('posts')
+
+    useEffect(() => {
+        list.trigger({}) // Fetch all posts
+    }, [])
+
+    return (
+        <VStack>
+            {posts.map((post) => (
+                <HStack key={post.id}>
+                    <Link href={`/posts/${post.id}`}>
+                        <Text>{post.title}</Text>
+                    </Link>
+                    <IconButton
+                        onClick={() => remove.trigger({id: post.id})}
+                        disabled={remove.loading}
+                        icon={<LuTrash />}
+                    />
+                </HStack>
+            ))}
+        </VStack>
+    )
+}
+```
+
+#### `useSingle`
+To work with a single record, often used within a `SingleProvider`.
+
+`app/posts/[id]/page.tsx`:
+```tsx
+'use client'
+import { useSingle } from '@/app/interface'
+
+export default function PostPage() {
+    // Get the current post from the context provided by SingleProvider
+    const { single: post } = useSingle('posts')
+
+    return (
+        <article>
+            <h1>{post.title}</h1>
+            <p>{post.content}</p>
+        </article>
+    )
+}
+```
+
+### Step 7: High-Level Abstracted Forms
+
+The framework provides `CreateForm` and `UpdateForm` components that handle form state, submission, and API calls for you.
+
+`app/posts/new/page.tsx`:
+```tsx
+'use client'
+import { CreateForm } from '@/app/interface'
+import { Input, Button, Textarea } from '@chakra-ui/react'
+
+export function NewPostPage() {
+    const { user } = useUser() // from @auth0/nextjs-auth0/client
+
+    return (
+        <CreateForm 
+            table='posts'
+            // Set default values for the form
+            defaults={{ authorId: user.id, title: 'New Post' }}
+            onSuccess={(post) => router.push(`/posts/${post.id}`)}
+        >
+            {/* The child is a render prop with form state and field state */}
+            {({ loading, fields, setField, submit }) => (
+                <form onSubmit={submit}>
+                    <Input 
+                        value={fields.title}
+                        onChange={(e) => setField('title', e.target.value)}
+                    />
+                    <Textarea
+                        value={fields.content}
+                        onChange={(e) => setField('content', e.target.value)}
+                    />
+                    <Button type='submit' disabled={loading}>
+                        {loading ? 'Saving...' : 'Create Post'}
+                    </Button>
+                </form>
+            )}
+        </CreateForm>
+    )
+}
+```
+
+#### `FilterForm`
+Use `FilterForm` to easily create search and filter functionality. It wraps the `list` method of a table and displays the results.
+
+`app/posts/SearchPosts.tsx`:
+```tsx
+'use client'
+import { FilterForm } from '@/app/interface'
+import { Input, Button, VStack, Text, Box } from '@chakra-ui/react'
+
+function SearchPosts() {
+    return (
+        <Box>
+            <FilterForm
+                table="posts"
+                // Set default filter values. The form will initially load with these.
+                defaults={{ title: '' }}
+            >
+                {({ loading, fields, setField, submit, result }) => (
+                    <VStack as="form" onSubmit={submit} align="stretch" spacing={4}>
+                        <Input
+                            placeholder="Search by title..."
+                            value={fields.title}
+                            onChange={(e) => setField('title', e.target.value)}
+                        />
+                        <Button type="submit" disabled={loading} alignSelf="flex-start">
+                            {loading ? 'Searching...' : 'Search'}
+                        </Button>
+
+                        {/* Display the results from the list call */}
+                        <VStack align="stretch" mt={4} spacing={2}>
+                            {result && result.length > 0 ? (
+                                result.map(post => (
+                                    <Text key={post.id}>- {post.title}</Text>
+                                ))
+                            ) : (
+                                <Text color="gray.500">No results found.</Text>
+                            )}
+                        </VStack>
+                    </VStack>
+                )}
+            </FilterForm>
+        </Box>
+    );
+}
+```
+
+## Form and Field Primitives
+
+The `CreateForm` and `UpdateForm` components are convenient abstractions. For more control, you can use the underlying `FormProvider` and `FieldsProvider` primitives directly.
+
+### `packages/form.tsx`
+
+`FormProvider` is a render-prop component that wraps your form submission logic. It manages the `loading`, `error`, and `result` state of an async callback.
+
+- **Props**:
+    - `callback`: An async function that takes the form data and performs the submission.
+    - `data`: The initial data for the form.
+    - `onSuccess`: An optional function to call with the result of a successful submission.
+- **Render Prop State**:
+    - `loading`: `boolean` - True while the callback is executing.
+    - `error`: `Error | null` - The error object if the submission fails.
+    - `result`: `Result | null` - The data returned from a successful submission.
+    - `submit`: `function` - The function to trigger the form submission.
+    - `values`: `Fields` - The current data object for the form.
+
+### `packages/fields.tsx`
+
+`FieldsProvider` manages the state of your form's input fields. It holds the `fields` object and provides `setField` and `setFields` methods to update it.
+
+- **Props**:
+    - `defaults`: The initial values for the form fields.
+- **Render Prop State**:
+    - `fields`: `T` - The object containing the current state of all form fields.
+    - `setField`: `(name, value)` - A function to update a single field's value.
+    - `setFields`: `(newFields)` - A function to replace the entire fields object.
+
+### Using `FormProvider` and `FieldsProvider` Together
+
+Here is how you can build a form from scratch using the low-level primitives. This pattern is what `CreateForm` uses internally.
+
+```tsx
+import { FormProvider } from 'asasvirtuais/form'
+import { FieldsProvider } from 'asasvirtuais/fields'
+import { Input, Button, Spinner, Text, Textarea, Stack } from '@chakra-ui/react'
+
+function NewPostForm({ onCreate }) {
+    // The function that will be called on form submission
+    const createPostCallback = async (fields) => {
+        // This would typically be an API call, e.g., from useTable()
+        const newPost = await api.posts.create({ data: fields });
+        return newPost;
+    };
+
+    return (
+        // 1. FormProvider handles the submission process
+        <FormProvider callback={createPostCallback} data={{}} onSuccess={onCreate}>
+            {({ loading, error, submit }) => (
+                // 2. FieldsProvider manages the state of the form's inputs
+                <FieldsProvider defaults={{ title: '', content: '', authorId: '1' }}>
+                    {({ fields, setField }) => (
+                        <form onSubmit={(e) => {
+                            e.preventDefault();
+                            // Pass the current field state to the submit function
+                            submit(fields);
+                        }}>
+                            <Stack>
+                                <label>Title</label>
+                                <Input
+                                    value={fields.title}
+                                    onChange={(e) => setField('title', e.target.value)}
+                                />
+
+                                <label>Content</label>
+                                <Textarea
+                                    value={fields.content}
+                                    onChange={(e) => setField('content', e.target.value)}
+                                />
+
+                                {error && <Text color="red.500">{error.message}</Text>}
+
+                                <Button type="submit" disabled={loading}>
+                                    {loading ? <Spinner /> : 'Create Post'}
+                                </Button>
+                            </Stack>
+                        </form>
+                    )}
+                </FieldsProvider>
+            )}
+        </FormProvider>
+    );
+}
+```
+
+## Roadmap
+
+- [ ] Relationships, linked records, TableLookup field
+- [ ] Realtime database with feathersjs

package/hooks/useOpenRouterModels.ts

@@ -1,80 +1,80 @@
-'use client'
-import { useState, useEffect } from 'react'
-
-export interface OpenRouterModel {
-  id: string
-  name: string
-  description?: string
-  context_length?: number
-  pricing?: {
-    prompt?: string
-    completion?: string
-  }
-  architecture?: {
-    modality?: string
-  }
-}
-
-interface UseOpenRouterModelsResult {
-  models: OpenRouterModel[]
-  loading: boolean
-  error: string | null
-}
-
-export function useOpenRouterModels(): UseOpenRouterModelsResult {
-  const [models, setModels] = useState<OpenRouterModel[]>([])
-  const [loading, setLoading] = useState(true)
-  const [error, setError] = useState<string | null>(null)
-
-  useEffect(() => {
-    async function fetchModels() {
-      try {
-        setLoading(true)
-        setError(null)
-
-        const response = await fetch('https://openrouter.ai/api/v1/models', {
-          headers: {
-            'Content-Type': 'application/json',
-          },
-        })
-
-        if (!response.ok) {
-          throw new Error(`Failed to fetch models: ${response.statusText}`)
-        }
-
-        const data = await response.json()
-        
-        // Filter and sort models for better UX
-        const filteredModels = data.data
-          ?.filter((model: any) => 
-            model.id && 
-            model.name && 
-            !model.id.includes(':free') // Exclude free models for cleaner list
-          )
-          ?.sort((a: any, b: any) => a.name.localeCompare(b.name))
-          ?.slice(0, 50) || [] // Limit to 50 models for performance
-
-        setModels(filteredModels)
-      } catch (err) {
-        console.error('Error fetching OpenRouter models:', err)
-        setError(err instanceof Error ? err.message : 'Unknown error occurred')
-        
-        // Fallback to default models
-        setModels([
-          { id: 'openrouter/auto', name: 'Auto (Recommended)' },
-          { id: 'anthropic/claude-3.5-sonnet', name: 'Claude 3.5 Sonnet' },
-          { id: 'openai/gpt-4o', name: 'GPT-4o' },
-          { id: 'openai/gpt-4o-mini', name: 'GPT-4o Mini' },
-          { id: 'google/gemini-pro', name: 'Gemini Pro' },
-          { id: 'meta-llama/llama-3.1-8b-instruct', name: 'Llama 3.1 8B' },
-        ])
-      } finally {
-        setLoading(false)
-      }
-    }
-
-    fetchModels()
-  }, [])
-
-  return { models, loading, error }
+'use client'
+import { useState, useEffect } from 'react'
+
+export interface OpenRouterModel {
+  id: string
+  name: string
+  description?: string
+  context_length?: number
+  pricing?: {
+    prompt?: string
+    completion?: string
+  }
+  architecture?: {
+    modality?: string
+  }
+}
+
+interface UseOpenRouterModelsResult {
+  models: OpenRouterModel[]
+  loading: boolean
+  error: string | null
+}
+
+export function useOpenRouterModels(): UseOpenRouterModelsResult {
+  const [models, setModels] = useState<OpenRouterModel[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    async function fetchModels() {
+      try {
+        setLoading(true)
+        setError(null)
+
+        const response = await fetch('https://openrouter.ai/api/v1/models', {
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        })
+
+        if (!response.ok) {
+          throw new Error(`Failed to fetch models: ${response.statusText}`)
+        }
+
+        const data = await response.json()
+        
+        // Filter and sort models for better UX
+        const filteredModels = data.data
+          ?.filter((model: any) => 
+            model.id && 
+            model.name && 
+            !model.id.includes(':free') // Exclude free models for cleaner list
+          )
+          ?.sort((a: any, b: any) => a.name.localeCompare(b.name))
+          ?.slice(0, 50) || [] // Limit to 50 models for performance
+
+        setModels(filteredModels)
+      } catch (err) {
+        console.error('Error fetching OpenRouter models:', err)
+        setError(err instanceof Error ? err.message : 'Unknown error occurred')
+        
+        // Fallback to default models
+        setModels([
+          { id: 'openrouter/auto', name: 'Auto (Recommended)' },
+          { id: 'anthropic/claude-3.5-sonnet', name: 'Claude 3.5 Sonnet' },
+          { id: 'openai/gpt-4o', name: 'GPT-4o' },
+          { id: 'openai/gpt-4o-mini', name: 'GPT-4o Mini' },
+          { id: 'google/gemini-pro', name: 'Gemini Pro' },
+          { id: 'meta-llama/llama-3.1-8b-instruct', name: 'Llama 3.1 8B' },
+        ])
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchModels()
+  }, [])
+
+  return { models, loading, error }
 }

package/package.json

@@ -1,66 +1,67 @@
-{
-  "name": "asasvirtuais",
-  "type": "module",
-  "version": "0.4.4",
-  "directories": {
-    "packages": "./packages"
-  },
-  "exports": {
-    "./package.json": "./package.json",
-    "./*": "./packages/*",
-    "./*/*": "./packages/*/*"
-  },
-  "scripts": {
-    "code": "tmux new-session -d 'termux-wake-lock && sh dev-tunnel.sh'",
-    "dev": "next dev --port 3000 --hostname 0.0.0.0",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint",
-    "claude": "claude --dangerously-skip-permissions --mcp-config ./mcp.json",
-    "gemini": "gemini --yolo --all_files",
-    "env:pull": "vercel env pull .env"
-  },
-  "dependencies": {
-    "@ai-sdk/react": "^2.0.59",
-    "@asasvirtuais/airtable": "github:asasvirtuais/airtable#main",
-    "@asasvirtuais/chat": "github:asasvirtuais/chat#main",
-    "@asasvirtuais/crud": "github:asasvirtuais/crud#main",
-    "@asasvirtuais/react": "github:asasvirtuais/react#main",
-    "@auth0/nextjs-auth0": "^4.10.0",
-    "@chakra-ui/react": "^3.21.0",
-    "@emotion/react": "^11.14.0",
-    "@google-cloud/storage": "^7.16.0",
-    "@openrouter/ai-sdk-provider": "^1.0.0-beta.1",
-    "ai": "^5.0.49",
-    "asasvirtuais": "^0.2.0",
-    "date-fns": "^4.1.0",
-    "firebase": "^12.3.0",
-    "firebase-admin": "^13.5.0",
-    "google-auth-library": "^10.1.0",
-    "googleapis": "^153.0.0",
-    "jszip": "^3.10.1",
-    "knex": "^3.1.0",
-    "next": "15.6.0-canary.34",
-    "next-themes": "^0.4.6",
-    "openai": "^5.9.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-icons": "^5.5.0",
-    "react-markdown": "^10.1.0",
-    "react-use": "^17.6.0",
-    "remark-breaks": "^4.0.0",
-    "remark-gfm": "^4.0.1",
-    "search-params": "^4.0.1",
-    "wretch": "^2.11.0",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@anthropic-ai/claude-code": "^1.0.60",
-    "@google/gemini-cli": "^0.1.9",
-    "@types/node": "^20",
-    "@types/react": "^19",
-    "@types/react-dom": "^19",
-    "typescript": "^5",
-    "vercel": "^44.3.0"
-  }
-}
+{
+  "name": "asasvirtuais",
+  "type": "module",
+  "version": "0.5.0",
+  "directories": {
+    "packages": "./packages"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./*": "./packages/*",
+    "./*/*": "./packages/*/*"
+  },
+  "scripts": {
+    "code": "tmux new-session -d 'termux-wake-lock && sh dev-tunnel.sh'",
+    "dev": "next dev --port 3000 --hostname 0.0.0.0",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "claude": "claude --dangerously-skip-permissions --mcp-config ./mcp.json",
+    "gemini": "gemini --yolo --all-files",
+    "env:pull": "vercel env pull .env"
+  },
+  "dependencies": {
+    "@ai-sdk/react": "^2.0.60",
+    "@asasvirtuais/airtable": "github:asasvirtuais/airtable#main",
+    "@asasvirtuais/chat": "github:asasvirtuais/chat#main",
+    "@asasvirtuais/crud": "github:asasvirtuais/crud#main",
+    "@asasvirtuais/react": "github:asasvirtuais/react#main",
+    "@auth0/nextjs-auth0": "^4.10.0",
+    "@chakra-ui/react": "^3.27.0",
+    "@emotion/react": "^11.14.0",
+    "@google-cloud/storage": "^7.17.1",
+    "@openrouter/ai-sdk-provider": "^1.2.0",
+    "ai": "^5.0.60",
+    "asasvirtuais": "^0.4.4",
+    "date-fns": "^4.1.0",
+    "dexie": "^4.2.0",
+    "firebase": "^12.3.0",
+    "firebase-admin": "^13.5.0",
+    "google-auth-library": "^10.4.0",
+    "googleapis": "^161.0.0",
+    "jszip": "^3.10.1",
+    "knex": "^3.1.0",
+    "next": "15.6.0-canary.34",
+    "next-themes": "^0.4.6",
+    "openai": "^6.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-icons": "^5.5.0",
+    "react-markdown": "^10.1.0",
+    "react-use": "^17.6.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "search-params": "^4.0.1",
+    "wretch": "^2.11.0",
+    "zod": "^4.1.11"
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-code": "^2.0.8",
+    "@google/gemini-cli": "^0.7.0",
+    "@types/node": "^24.6.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "typescript": "^5.9.3",
+    "vercel": "^48.2.0"
+  }
+}

package/packages/dexie.ts

@@ -0,0 +1,126 @@
+import Dexie, { type Table } from 'dexie'
+import { z } from 'zod'
+import type { DatabaseInterface, TableInterface, Query } from 'asasvirtuais/interface'
+
+/**
+ * Creates a TableInterface adapter for IndexedDB using Dexie.js.
+ * This allows the framework to be used in a client-side only context.
+ *
+ * @param dbName The name of the IndexedDB database.
+ * @param schema The Zod schema definition for the database tables.
+ * @returns A TableInterface implementation for Dexie.
+ */
+export function dexieInterface<Schema extends DatabaseInterface>(
+    dbName: string,
+    schema: Schema
+): TableInterface<z.infer<Schema[keyof Schema]['readable']>, z.infer<Schema[keyof Schema]['writable']>> {
+
+    const db = new Dexie(dbName)
+
+    // Dynamically define the database schema for Dexie from the Zod schema.
+    // It marks 'id' as the primary key and indexes all other top-level readable fields.
+    const dexieSchema = Object.fromEntries(
+        Object.keys(schema).map(tableName => {
+            const fields = Object.keys(schema[tableName].readable.shape)
+            // 'id' is the primary key, the rest are indexed fields.
+            const indexedFields = fields.filter(f => f !== 'id').join(', ')
+            return [tableName, `id, ${indexedFields}`]
+        })
+    )
+
+    db.version(1).stores(dexieSchema)
+
+    type GenericReadable = z.infer<Schema[keyof Schema]['readable']>
+    type GenericWritable = z.infer<Schema[keyof Schema]['writable']>
+
+    return {
+        async find({ table, id }) {
+            if (!table) throw new Error('Table name must be provided.')
+            const result = await db.table(table).get(id)
+            if (!result) throw new Error(`Record with id ${id} not found in ${table}`)
+            return result
+        },
+
+        async list({ table, query }) {
+            if (!table) throw new Error('Table name must be provided.')
+            let collection = db.table(table).toCollection()
+
+            const { $limit, $skip, $sort, ...filters } = query ?? {}
+
+            // Handle filtering
+            if (Object.keys(filters).length > 0) {
+                collection = collection.filter(item => {
+                    return Object.entries(filters).every(([key, value]) => {
+                        const itemValue = item[key as keyof typeof item]
+                        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                            return Object.entries(value).every(([op, opValue]) => {
+                                switch (op) {
+                                    case '$ne': return itemValue !== opValue
+                                    case '$in': return Array.isArray(opValue) && opValue.includes(itemValue)
+                                    case '$nin': return Array.isArray(opValue) && !opValue.includes(itemValue)
+                                    case '$lt': return itemValue < (opValue as number)
+                                    case '$lte': return itemValue <= (opValue as number)
+                                    case '$gt': return itemValue > (opValue as number)
+                                    case '$gte': return itemValue >= (opValue as number)
+                                    default: return true // Ignore unknown operators
+                                }
+                            })
+                        } else {
+                            return itemValue === value
+                        }
+                    })
+                })
+            }
+
+            // Handle sorting
+            if ($sort) {
+                const sortKey = Object.keys($sort)[0] as keyof GenericReadable
+                const direction = $sort[sortKey] === -1 ? 'desc' : 'asc'
+                if (direction === 'desc') {
+                    collection = collection.reverse()
+                }
+                // @ts-expect-error
+                collection = await collection.sortBy(sortKey)
+            }
+
+            // Handle pagination
+            if ($skip) {
+                collection = collection.offset($skip)
+            }
+            if ($limit) {
+                collection = collection.limit($limit)
+            }
+
+            return collection.toArray()
+        },
+
+        async create({ table, data }) {
+            if (!table) throw new Error('Table name must be provided.')
+            // Use existing id or generate a new UUID
+            const id = (data as any).id || crypto.randomUUID()
+            const record = { ...data, id }
+            await db.table(table).add(record)
+            return record as GenericReadable
+        },
+
+        async update({ table, id, data }) {
+            if (!table) throw new Error('Table name must be provided.')
+            const updatedCount = await db.table(table).update(id, data)
+            if (updatedCount === 0) {
+                throw new Error(`Record with id ${id} not found in ${table}, cannot update.`)
+            }
+            const result = await this.find({ table, id })
+            return result as GenericReadable
+        },
+
+        async remove({ table, id }) {
+            if (!table) throw new Error('Table name must be provided.')
+            const record = await this.find({ table, id })
+            if (!record) {
+                 throw new Error(`Record with id ${id} not found in ${table}, cannot remove.`)
+            }
+            await db.table(table).delete(id)
+            return record as GenericReadable
+        },
+    } as TableInterface<GenericReadable, GenericWritable>
+}

package/tsconfig.json

@@ -15,7 +15,7 @@
     "incremental": true,
     "target": "ESNext",
     "module": "ESNext",
-    "moduleResolution": "node",
+    "moduleResolution": "bundler",
     "skipLibCheck": true,
     "plugins": [
       {