@taruvi/sdk 1.0.2 → 1.0.4

package/AI_IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,733 @@
+# Taruvi SDK - AI Implementation Guide
+
+> Quick reference for implementing Taruvi SDK features with copy-paste examples from production code
+
+## Installation
+
+```bash
+npm install @taruvi-io/sdk
+```
+
+## Core Setup
+
+### 1. Initialize Client
+
+```typescript
+import { Client } from '@taruvi-io/sdk'
+
+const taruviClient = new Client({
+  apiKey: "your-site-api-key",
+  appSlug: "your-app-slug", 
+  baseUrl: "https://taruvi-site.taruvi.cloud"
+})
+```
+
+### 2. Pass to Components (React)
+
+```typescript
+// App.tsx
+<Route path="/page" element={<MyPage taruviClient={taruviClient} />} />
+
+// MyPage.tsx
+interface MyPageProps {
+  taruviClient: Client;
+}
+
+export default function MyPage({ taruviClient }: MyPageProps) {
+  // Use SDK here
+}
+```
+
+---
+
+## Auth Service
+
+### Check Authentication
+
+```typescript
+import { Auth } from '@taruvi-io/sdk'
+
+const auth = new Auth(taruviClient)
+const isAuthenticated = await auth.isUserAuthenticated() // Returns boolean
+```
+
+### Login Flow
+
+```typescript
+import { useEffect } from "react"
+import { Auth } from '@taruvi-io/sdk'
+
+export default function Login({ taruviClient }) {
+  const auth = new Auth(taruviClient)
+
+  useEffect(() => {
+    const checkAuthAndRedirect = async () => {
+      const isAuthenticated = await auth.isUserAuthenticated()
+      
+      if (isAuthenticated) {
+        window.location.href = "/dashboard"
+      } else {
+        await auth.authenticateUser()
+      }
+    }
+    
+    checkAuthAndRedirect()
+  }, [])
+
+  return <div>Checking authentication...</div>
+}
+```
+
+---
+
+## User Service
+
+### Get Current User
+
+```typescript
+import { User } from '@taruvi-io/sdk'
+
+const user = new User(taruviClient)
+const userData = await user.getUserData()
+
+console.log(userData.data.username)
+console.log(userData.data.email)
+console.log(userData.data.full_name)
+```
+
+### Create User (Registration)
+
+```typescript
+import { User } from '@taruvi-io/sdk'
+
+const user = new User(taruviClient)
+
+const newUser = await user.createUser({
+  username: "john_doe",
+  email: "john@example.com",
+  password: "secure123",
+  confirm_password: "secure123",
+  first_name: "John",
+  last_name: "Doe",
+  is_active: true,
+  is_staff: false,
+  attributes: ""
+})
+```
+
+### Update User
+
+```typescript
+const user = new User(taruviClient)
+
+await user.updateUser("john_doe", {
+  email: "newemail@example.com",
+  first_name: "Johnny"
+})
+```
+
+### Delete User
+
+```typescript
+const user = new User(taruviClient)
+await user.deleteUser("john_doe")
+```
+
+### Complete Registration Form Example
+
+```typescript
+import { useState } from "react"
+import { User } from "@taruvi-io/sdk"
+import { useNavigate } from "react-router"
+
+export default function Register({ taruviClient }) {
+  const navigate = useNavigate()
+  const [formData, setFormData] = useState({
+    username: "",
+    email: "",
+    password: "",
+    confirm_password: "",
+    first_name: "",
+    last_name: "",
+    is_active: true,
+    is_staff: false
+  })
+  const [error, setError] = useState("")
+  const [loading, setLoading] = useState(false)
+
+  const handleSubmit = async (e) => {
+    e.preventDefault()
+    
+    if (formData.password !== formData.confirm_password) {
+      setError("Passwords do not match")
+      return
+    }
+
+    setLoading(true)
+    try {
+      const userClient = new User(taruviClient)
+      await userClient.createUser(formData)
+      navigate("/login")
+    } catch (err) {
+      setError(err.message || "Failed to create user")
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        name="username"
+        value={formData.username}
+        onChange={(e) => setFormData({...formData, username: e.target.value})}
+        required
+      />
+      {/* Add other fields */}
+      <button type="submit" disabled={loading}>
+        {loading ? "Creating..." : "Register"}
+      </button>
+      {error && <div>{error}</div>}
+    </form>
+  )
+}
+```
+
+---
+
+## Database Service (CRUD Operations)
+
+### Fetch All Records
+
+```typescript
+import { Database } from '@taruvi-io/sdk'
+
+const db = new Database(taruviClient)
+const response = await db.from("accounts").execute()
+
+if (response.data) {
+  console.log(response.data) // Array of records
+}
+```
+
+### Fetch Single Record
+
+```typescript
+const db = new Database(taruviClient)
+const record = await db.from("accounts").get("record-id").execute()
+```
+
+### Update Record
+
+```typescript
+const db = new Database(taruviClient)
+await db.from("accounts").get("record-id").update({
+  name: "Updated Name",
+  status: "active"
+}).execute()
+```
+
+### Delete Record
+
+```typescript
+const db = new Database(taruviClient)
+await db.from("accounts").delete("record-id").execute()
+```
+
+### Filter Records
+
+```typescript
+const db = new Database(taruviClient)
+const filtered = await db
+  .from("accounts")
+  .filter({
+    status: "active",
+    country: "USA"
+  })
+  .execute()
+```
+
+### Complete CRUD Example (CRM Table)
+
+```typescript
+import { useEffect, useState } from 'react'
+import { Database } from '@taruvi-io/sdk'
+
+export default function CrmTable({ taruviClient }) {
+  const [contacts, setContacts] = useState([])
+
+  const fetchContacts = async () => {
+    const db = new Database(taruviClient)
+    const response = await db.from("accounts").execute()
+    if (response.data) {
+      setContacts(response.data)
+    }
+  }
+
+  useEffect(() => {
+    fetchContacts()
+  }, [])
+
+  const handleDelete = async (id) => {
+    const db = new Database(taruviClient)
+    await db.from("accounts").delete(id).execute()
+    fetchContacts() // Refresh
+  }
+
+  const handleUpdate = async (id, data) => {
+    const db = new Database(taruviClient)
+    await db.from("accounts").get(id).update(data).execute()
+    fetchContacts() // Refresh
+  }
+
+  return (
+    <table>
+      {contacts.map(contact => (
+        <tr key={contact.id}>
+          <td>{contact.name}</td>
+          <td>
+            <button onClick={() => handleUpdate(contact.id, { status: 'updated' })}>
+              Edit
+            </button>
+            <button onClick={() => handleDelete(contact.id)}>
+              Delete
+            </button>
+          </td>
+        </tr>
+      ))}
+    </table>
+  )
+}
+```
+
+---
+
+## Storage Service (File Management)
+
+### List Files in Bucket
+
+```typescript
+import { Storage } from '@taruvi-io/sdk'
+
+const storage = new Storage(taruviClient, {})
+const files = await storage.from("documents").execute()
+
+console.log(files.data) // Array of file objects
+```
+
+### Upload Files
+
+```typescript
+const storage = new Storage(taruviClient, {})
+
+const filesData = {
+  files: [file1, file2], // File objects from input
+  metadatas: [{ name: "file1" }, { name: "file2" }],
+  paths: ["file1.pdf", "file2.pdf"]
+}
+
+await storage.from("documents").upload(filesData).execute()
+```
+
+### Delete File
+
+```typescript
+const storage = new Storage(taruviClient, {})
+await storage.from("documents").delete("path/to/file.pdf").execute()
+```
+
+### Update File Metadata
+
+```typescript
+const storage = new Storage(taruviClient, {})
+await storage
+  .from("documents")
+  .update("path/to/file.pdf", {
+    filename: "newname.pdf",
+    visibility: "public",
+    metadata: { category: "reports" }
+  })
+  .execute()
+```
+
+### Filter Files
+
+```typescript
+const storage = new Storage(taruviClient, {})
+const filtered = await storage
+  .from("documents")
+  .filter({
+    search: "invoice",
+    visibility: "public",
+    mimetype_category: "document",
+    min_size: 1024,
+    ordering: "-created_at"
+  })
+  .execute()
+```
+
+### Complete File Upload Example
+
+```typescript
+import { useState, useRef } from 'react'
+import { Storage } from '@taruvi-io/sdk'
+
+export default function FileUploader({ taruviClient }) {
+  const [files, setFiles] = useState([])
+  const [uploading, setUploading] = useState(false)
+  const fileInputRef = useRef(null)
+
+  const handleFileSelect = (e) => {
+    const selectedFiles = Array.from(e.target.files)
+    setFiles(selectedFiles)
+  }
+
+  const uploadFiles = async () => {
+    if (files.length === 0) return
+
+    setUploading(true)
+    try {
+      const storage = new Storage(taruviClient, {})
+      
+      const uploadData = {
+        files: files,
+        metadatas: files.map(f => ({ name: f.name })),
+        paths: files.map(f => f.name)
+      }
+
+      await storage.from("documents").upload(uploadData).execute()
+      
+      alert("Upload successful!")
+      setFiles([])
+    } catch (error) {
+      alert("Upload failed: " + error.message)
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  return (
+    <div>
+      <input
+        ref={fileInputRef}
+        type="file"
+        multiple
+        onChange={handleFileSelect}
+      />
+      <button onClick={uploadFiles} disabled={uploading || files.length === 0}>
+        {uploading ? "Uploading..." : `Upload ${files.length} file(s)`}
+      </button>
+    </div>
+  )
+}
+```
+
+---
+
+## Functions Service (Serverless)
+
+### Execute Function (Sync)
+
+```typescript
+import { Functions } from '@taruvi-io/sdk'
+
+const functions = new Functions(taruviClient)
+
+const result = await functions.execute("my-function", {
+  async: false,
+  params: {
+    key1: "value1",
+    key2: 123
+  }
+})
+
+console.log(result.data) // Function response
+```
+
+### Execute Function (Async)
+
+```typescript
+const functions = new Functions(taruviClient)
+
+const result = await functions.execute("long-running-task", {
+  async: true,
+  params: { data: "value" }
+})
+
+console.log(result.invocation.invocation_id) // Track async execution
+console.log(result.invocation.celery_task_id)
+console.log(result.invocation.status)
+```
+
+### Complete Function Executor Example
+
+```typescript
+import { useState } from 'react'
+import { Functions } from '@taruvi-io/sdk'
+
+export default function FunctionExecutor({ taruviClient }) {
+  const [functionSlug, setFunctionSlug] = useState("")
+  const [params, setParams] = useState({})
+  const [isAsync, setIsAsync] = useState(false)
+  const [result, setResult] = useState(null)
+  const [loading, setLoading] = useState(false)
+
+  const executeFunction = async () => {
+    setLoading(true)
+    try {
+      const functions = new Functions(taruviClient)
+      const response = await functions.execute(functionSlug, {
+        async: isAsync,
+        params: params
+      })
+      setResult(response)
+    } catch (error) {
+      console.error(error)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div>
+      <input
+        placeholder="Function slug"
+        value={functionSlug}
+        onChange={(e) => setFunctionSlug(e.target.value)}
+      />
+      <label>
+        <input
+          type="checkbox"
+          checked={isAsync}
+          onChange={(e) => setIsAsync(e.target.checked)}
+        />
+        Async
+      </label>
+      <button onClick={executeFunction} disabled={loading}>
+        Execute
+      </button>
+      {result && <pre>{JSON.stringify(result, null, 2)}</pre>}
+    </div>
+  )
+}
+```
+
+---
+
+## Settings Service
+
+### Get Site Settings
+
+```typescript
+import { Settings } from '@taruvi-io/sdk'
+
+const settings = new Settings(taruviClient)
+const config = await settings.get()
+
+console.log(config) // Site configuration object
+```
+
+### Update Setting
+
+```typescript
+const settings = new Settings(taruviClient)
+await settings.update("setting_key", { value: "new_value" }).execute()
+```
+
+---
+
+## Secrets Service
+
+### List Secrets
+
+```typescript
+import { Secrets } from '@taruvi-io/sdk'
+
+const secrets = new Secrets(taruviClient)
+const result = await secrets.list().execute()
+
+console.log(result.items) // Array of secrets
+```
+
+### Update Secret
+
+```typescript
+const secrets = new Secrets(taruviClient)
+
+await secrets.update("MY_SECRET", {
+  value: {
+    hostname: "db.example.com",
+    port_number: 3306,
+    username: "admin",
+    password: "secret123"
+  },
+  tags: ["mysql", "production"],
+  secret_type: "Mysql"
+}).execute()
+```
+
+---
+
+## Common Patterns
+
+### Loading States
+
+```typescript
+const [data, setData] = useState(null)
+const [loading, setLoading] = useState(true)
+const [error, setError] = useState(null)
+
+useEffect(() => {
+  const fetchData = async () => {
+    setLoading(true)
+    try {
+      const db = new Database(taruviClient)
+      const response = await db.from("table").execute()
+      setData(response.data)
+    } catch (err) {
+      setError(err.message)
+    } finally {
+      setLoading(false)
+    }
+  }
+  fetchData()
+}, [])
+
+if (loading) return <div>Loading...</div>
+if (error) return <div>Error: {error}</div>
+return <div>{/* Render data */}</div>
+```
+
+### Error Handling
+
+```typescript
+try {
+  const user = new User(taruviClient)
+  await user.createUser(data)
+} catch (error) {
+  if (error.response?.status === 400) {
+    console.error("Validation error:", error.response.data)
+  } else if (error.response?.status === 401) {
+    console.error("Unauthorized")
+  } else {
+    console.error("Unknown error:", error.message)
+  }
+}
+```
+
+### Refresh Data After Mutation
+
+```typescript
+const [items, setItems] = useState([])
+
+const fetchItems = async () => {
+  const db = new Database(taruviClient)
+  const response = await db.from("items").execute()
+  setItems(response.data || [])
+}
+
+const deleteItem = async (id) => {
+  const db = new Database(taruviClient)
+  await db.from("items").delete(id).execute()
+  await fetchItems() // Refresh list
+}
+
+const updateItem = async (id, data) => {
+  const db = new Database(taruviClient)
+  await db.from("items").get(id).update(data).execute()
+  await fetchItems() // Refresh list
+}
+```
+
+---
+
+## TypeScript Types
+
+### Import Types
+
+```typescript
+import type { 
+  TaruviConfig,
+  UserCreateRequest,
+  UserResponse,
+  UserDataResponse,
+  FunctionRequest,
+  FunctionResponse,
+  StorageFilters,
+  DatabaseFilters
+} from '@taruvi-io/sdk'
+```
+
+### Type Usage
+
+```typescript
+const config: TaruviConfig = {
+  apiKey: "key",
+  appSlug: "app",
+  baseUrl: "https://api.taruvi.cloud"
+}
+
+const userData: UserCreateRequest = {
+  username: "john",
+  email: "john@example.com",
+  password: "pass123",
+  confirm_password: "pass123",
+  first_name: "John",
+  last_name: "Doe"
+}
+```
+
+---
+
+## Quick Reference
+
+| Service | Import | Purpose |
+|---------|--------|---------|
+| `Client` | `import { Client }` | Main SDK client |
+| `Auth` | `import { Auth }` | Authentication |
+| `User` | `import { User }` | User management |
+| `Database` | `import { Database }` | App data CRUD |
+| `Storage` | `import { Storage }` | File management |
+| `Functions` | `import { Functions }` | Serverless functions |
+| `Settings` | `import { Settings }` | Site configuration |
+| `Secrets` | `import { Secrets }` | Sensitive data |
+
+---
+
+## Chaining Pattern
+
+All query-building services use method chaining:
+
+```typescript
+// Database
+await db.from("table").get("id").update(data).execute()
+await db.from("table").filter({ status: "active" }).execute()
+
+// Storage
+await storage.from("bucket").delete("path").execute()
+await storage.from("bucket").filter({ search: "query" }).execute()
+```
+
+**Always call `.execute()` at the end to run the query!**
+
+---
+
+## Environment Variables
+
+```env
+VITE_TARUVI_API_KEY=your-api-key
+VITE_TARUVI_APP_SLUG=your-app
+VITE_TARUVI_BASE_URL=https://taruvi-site.taruvi.cloud
+```
+
+```typescript
+const client = new Client({
+  apiKey: import.meta.env.VITE_TARUVI_API_KEY,
+  appSlug: import.meta.env.VITE_TARUVI_APP_SLUG,
+  baseUrl: import.meta.env.VITE_TARUVI_BASE_URL
+})
+```
+
+---
+
+**Generated from production code examples • Last updated: 2025-12-15**