@taruvi/sdk 1.0.6 → 1.0.8

package/AI_IMPLEMENTATION_GUIDE.md

@@ -8,6 +8,16 @@
 npm install @taruvi-io/sdk
 ```
 
+## What's New
+
+Recent updates to the SDK:
+
+- **Auth Service**: New Web UI Flow with `login()`, `signup()`, `logout()` methods that redirect to backend pages. Token refresh with rotation support, `getCurrentUser()` for JWT decoding.
+- **Database Service**: Added `create()` method for creating records. Comprehensive filter support with Django-style operators (`__gte`, `__lte`, `__icontains`, etc.).
+- **Storage Service**: Added `download()` method. Enhanced filter support with size, date, MIME type, visibility filters. `delete()` now accepts array of paths for bulk deletion.
+- **Client**: Automatic token extraction from URL hash after OAuth callback - no manual token handling needed.
+- **Types**: Comprehensive `StorageFilters` and `DatabaseFilters` interfaces with full operator support.
+
 ## Core Setup
 
 ### 1. Initialize Client
@@ -38,6 +48,23 @@ export default function MyPage({ taruviClient }: MyPageProps) {
 }
 ```
 
+### 3. Automatic Token Handling
+
+The Client automatically extracts authentication tokens from URL hash after OAuth callback:
+
+```typescript
+// After login redirect, URL contains:
+// #session_token=xxx&access_token=yyy&refresh_token=zzz&expires_in=172800&token_type=Bearer
+
+// Client automatically:
+// 1. Extracts tokens from URL hash
+// 2. Stores them in TokenClient
+// 3. Clears the hash from URL
+
+const taruviClient = new Client({ apiKey, appSlug, baseUrl })
+// Tokens are now available automatically if present in URL hash
+```
+
 ---
 
 ## Auth Service
@@ -48,10 +75,10 @@ export default function MyPage({ taruviClient }: MyPageProps) {
 import { Auth } from '@taruvi-io/sdk'
 
 const auth = new Auth(taruviClient)
-const isAuthenticated = await auth.isUserAuthenticated() // Returns boolean
+const isAuthenticated = auth.isUserAuthenticated() // Returns boolean (synchronous)
 ```
 
-### Login Flow
+### Login Flow (Web UI Flow with Redirect)
 
 ```typescript
 import { useEffect } from "react"
@@ -61,23 +88,81 @@ 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()
-      }
+    const isAuthenticated = auth.isUserAuthenticated()
+
+    if (isAuthenticated) {
+      window.location.href = "/dashboard"
+    } else {
+      // Redirects to backend login page, then returns with tokens in URL hash
+      auth.login() // Optional: pass callback URL
     }
-    
-    checkAuthAndRedirect()
   }, [])
 
   return <div>Checking authentication...</div>
 }
 ```
 
+### Signup Flow
+
+```typescript
+import { Auth } from '@taruvi-io/sdk'
+
+const auth = new Auth(taruviClient)
+
+// Redirect to signup page (Web UI Flow)
+auth.signup() // Optional: pass callback URL
+auth.signup("/dashboard") // Redirect to dashboard after signup
+```
+
+### Logout
+
+```typescript
+import { Auth } from '@taruvi-io/sdk'
+
+const auth = new Auth(taruviClient)
+
+// Clear tokens and redirect to logout page
+auth.logout() // Optional: pass callback URL
+auth.logout("/") // Redirect to home after logout
+```
+
+### Get Current User
+
+```typescript
+import { Auth } from '@taruvi-io/sdk'
+
+const auth = new Auth(taruviClient)
+
+// Get user info from decoded JWT access token
+const user = auth.getCurrentUser()
+console.log(user?.user_id)
+console.log(user?.username)
+console.log(user?.email)
+```
+
+### Token Management
+
+```typescript
+import { Auth } from '@taruvi-io/sdk'
+
+const auth = new Auth(taruviClient)
+
+// Get tokens
+const accessToken = auth.getAccessToken()
+const refreshToken = auth.getRefreshToken()
+
+// Check if token is expired
+const isExpired = auth.isTokenExpired()
+
+// Refresh access token (returns new access AND refresh tokens due to rotation)
+const newTokens = await auth.refreshAccessToken()
+if (newTokens) {
+  console.log(newTokens.access)
+  console.log(newTokens.refresh)
+  console.log(newTokens.expires_in)
+}
+```
+
 ---
 
 ## User Service
@@ -217,6 +302,17 @@ const db = new Database(taruviClient)
 const record = await db.from("accounts").get("record-id").execute()
 ```
 
+### Create Record
+
+```typescript
+const db = new Database(taruviClient)
+await db.from("accounts").create({
+  name: "John Doe",
+  email: "john@example.com",
+  status: "active"
+}).execute()
+```
+
 ### Update Record
 
 ```typescript
@@ -238,6 +334,8 @@ await db.from("accounts").delete("record-id").execute()
 
 ```typescript
 const db = new Database(taruviClient)
+
+// Simple field filters
 const filtered = await db
   .from("accounts")
   .filter({
@@ -245,6 +343,27 @@ const filtered = await db
     country: "USA"
   })
   .execute()
+
+// Advanced filters with operators
+const advanced = await db
+  .from("accounts")
+  .filter({
+    age__gte: 18,           // age >= 18
+    age__lt: 65,            // age < 65
+    name__icontains: "john", // case-insensitive contains
+    created_at__gte: "2024-01-01",
+    ordering: "-created_at"  // Sort by created_at descending
+  })
+  .execute()
+
+// Pagination
+const paginated = await db
+  .from("accounts")
+  .filter({
+    page: 1,
+    pageSize: 20
+  })
+  .execute()
 ```
 
 ### Complete CRUD Example (CRM Table)
@@ -268,6 +387,12 @@ export default function CrmTable({ taruviClient }) {
     fetchContacts()
   }, [])
 
+  const handleCreate = async (data) => {
+    const db = new Database(taruviClient)
+    await db.from("accounts").create(data).execute()
+    fetchContacts() // Refresh
+  }
+
   const handleDelete = async (id) => {
     const db = new Database(taruviClient)
     await db.from("accounts").delete(id).execute()
@@ -281,21 +406,26 @@ export default function CrmTable({ taruviClient }) {
   }
 
   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>
+    <div>
+      <button onClick={() => handleCreate({ name: 'New Contact', status: 'active' })}>
+        Add Contact
+      </button>
+      <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>
+    </div>
   )
 }
 ```
@@ -309,7 +439,7 @@ export default function CrmTable({ taruviClient }) {
 ```typescript
 import { Storage } from '@taruvi-io/sdk'
 
-const storage = new Storage(taruviClient, {})
+const storage = new Storage(taruviClient)
 const files = await storage.from("documents").execute()
 
 console.log(files.data) // Array of file objects
@@ -318,7 +448,7 @@ console.log(files.data) // Array of file objects
 ### Upload Files
 
 ```typescript
-const storage = new Storage(taruviClient, {})
+const storage = new Storage(taruviClient)
 
 const filesData = {
   files: [file1, file2], // File objects from input
@@ -329,17 +459,33 @@ const filesData = {
 await storage.from("documents").upload(filesData).execute()
 ```
 
-### Delete File
+### Download File
 
 ```typescript
-const storage = new Storage(taruviClient, {})
-await storage.from("documents").delete("path/to/file.pdf").execute()
+const storage = new Storage(taruviClient)
+const file = await storage.from("documents").download("path/to/file.pdf").execute()
+```
+
+### Delete Files
+
+```typescript
+const storage = new Storage(taruviClient)
+
+// Delete single file
+await storage.from("documents").delete(["path/to/file.pdf"]).execute()
+
+// Delete multiple files
+await storage.from("documents").delete([
+  "path/to/file1.pdf",
+  "path/to/file2.pdf",
+  "path/to/file3.pdf"
+]).execute()
 ```
 
 ### Update File Metadata
 
 ```typescript
-const storage = new Storage(taruviClient, {})
+const storage = new Storage(taruviClient)
 await storage
   .from("documents")
   .update("path/to/file.pdf", {
@@ -353,7 +499,9 @@ await storage
 ### Filter Files
 
 ```typescript
-const storage = new Storage(taruviClient, {})
+const storage = new Storage(taruviClient)
+
+// Basic filters
 const filtered = await storage
   .from("documents")
   .filter({
@@ -364,6 +512,39 @@ const filtered = await storage
     ordering: "-created_at"
   })
   .execute()
+
+// Advanced filters with operators
+const advanced = await storage
+  .from("documents")
+  .filter({
+    // Size filters (bytes)
+    size__gte: 1024,           // >= 1KB
+    size__lte: 10485760,       // <= 10MB
+
+    // Date filters (ISO 8601)
+    created_at__gte: "2024-01-01",
+    created_at__lte: "2024-12-31",
+
+    // Search filters
+    filename__icontains: "report",
+    file__startswith: "invoice",
+    prefix: "uploads/2024/",
+
+    // MIME type filters
+    mimetype: "application/pdf",
+    mimetype_category: "image",  // image, document, video, audio, etc.
+
+    // Visibility & user filters
+    visibility: "public",
+    created_by_me: true,
+    created_by__username: "john",
+
+    // Pagination & sorting
+    page: 1,
+    pageSize: 50,
+    ordering: "-created_at"  // Sort by created_at descending
+  })
+  .execute()
 ```
 
 ### Complete File Upload Example
@@ -387,8 +568,8 @@ export default function FileUploader({ taruviClient }) {
 
     setUploading(true)
     try {
-      const storage = new Storage(taruviClient, {})
-      
+      const storage = new Storage(taruviClient)
+
       const uploadData = {
         files: files,
         metadatas: files.map(f => ({ name: f.name })),
@@ -396,7 +577,7 @@ export default function FileUploader({ taruviClient }) {
       }
 
       await storage.from("documents").upload(uploadData).execute()
-      
+
       alert("Upload successful!")
       setFiles([])
     } catch (error) {
@@ -626,6 +807,12 @@ const fetchItems = async () => {
   setItems(response.data || [])
 }
 
+const createItem = async (data) => {
+  const db = new Database(taruviClient)
+  await db.from("items").create(data).execute()
+  await fetchItems() // Refresh list
+}
+
 const deleteItem = async (id) => {
   const db = new Database(taruviClient)
   await db.from("items").delete(id).execute()
@@ -646,15 +833,25 @@ const updateItem = async (id, data) => {
 ### Import Types
 
 ```typescript
-import type { 
+import type {
   TaruviConfig,
+  AuthTokens,
   UserCreateRequest,
   UserResponse,
   UserDataResponse,
   FunctionRequest,
   FunctionResponse,
+  FunctionInvocation,
+  DatabaseRequest,
+  DatabaseResponse,
+  DatabaseFilters,
+  StorageRequest,
+  StorageUpdateRequest,
+  StorageResponse,
   StorageFilters,
-  DatabaseFilters
+  SettingsResponse,
+  SecretRequest,
+  SecretResponse
 } from '@taruvi-io/sdk'
 ```
 
@@ -664,7 +861,9 @@ import type {
 const config: TaruviConfig = {
   apiKey: "key",
   appSlug: "app",
-  baseUrl: "https://api.taruvi.cloud"
+  baseUrl: "https://api.taruvi.cloud",
+  deskUrl: "https://desk.taruvi.cloud", // optional
+  token: "existing-token" // optional
 }
 
 const userData: UserCreateRequest = {
@@ -673,12 +872,80 @@ const userData: UserCreateRequest = {
   password: "pass123",
   confirm_password: "pass123",
   first_name: "John",
-  last_name: "Doe"
+  last_name: "Doe",
+  is_active: true,
+  is_staff: false
+}
+
+// Database filters with operators
+const dbFilters: DatabaseFilters = {
+  page: 1,
+  pageSize: 20,
+  ordering: "-created_at",
+  status: "active",
+  age__gte: 18,
+  name__icontains: "john"
+}
+
+// Storage filters with comprehensive options
+const storageFilters: StorageFilters = {
+  page: 1,
+  pageSize: 50,
+  search: "invoice",
+  visibility: "public",
+  mimetype_category: "document",
+  size__gte: 1024,
+  size__lte: 10485760,
+  created_at__gte: "2024-01-01",
+  ordering: "-created_at",
+  created_by_me: true
 }
 ```
 
 ---
 
+## Filter Operators Reference
+
+### Database Filter Operators (Django-style)
+
+The Database service supports Django-style field lookups:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `field` | Exact match | `{ status: "active" }` |
+| `field__gte` | Greater than or equal | `{ age__gte: 18 }` |
+| `field__gt` | Greater than | `{ age__gt: 17 }` |
+| `field__lte` | Less than or equal | `{ age__lte: 65 }` |
+| `field__lt` | Less than | `{ age__lt: 66 }` |
+| `field__icontains` | Case-insensitive contains | `{ name__icontains: "john" }` |
+| `field__contains` | Case-sensitive contains | `{ name__contains: "John" }` |
+| `field__istartswith` | Case-insensitive starts with | `{ email__istartswith: "admin" }` |
+| `field__startswith` | Case-sensitive starts with | `{ code__startswith: "PRE" }` |
+| `field__iendswith` | Case-insensitive ends with | `{ domain__iendswith: ".com" }` |
+| `field__endswith` | Case-sensitive ends with | `{ filename__endswith: ".pdf" }` |
+| `field__in` | Value in list | `{ status__in: ["active", "pending"] }` |
+| `field__isnull` | Is null check | `{ deleted_at__isnull: true }` |
+| `ordering` | Sort results | `{ ordering: "-created_at" }` (- for desc) |
+| `page` | Page number | `{ page: 1 }` |
+| `pageSize` | Items per page | `{ pageSize: 20 }` |
+
+### Storage Filter Options
+
+The Storage service supports these specialized filters:
+
+| Category | Filters | Description |
+|----------|---------|-------------|
+| **Size** | `size__gte`, `size__lte`, `size__gt`, `size__lt`, `min_size`, `max_size` | Filter by file size in bytes |
+| **Dates** | `created_at__gte`, `created_at__lte`, `created_after`, `created_before`, `updated_at__gte`, `updated_at__lte` | Filter by dates (ISO 8601 format) |
+| **Search** | `search`, `filename__icontains`, `prefix`, `file`, `file__icontains`, `file__startswith`, `file__istartswith`, `metadata_search` | Search for files |
+| **MIME Type** | `mimetype`, `mimetype__in`, `mimetype_category` | Filter by file type (document, image, video, audio, etc.) |
+| **Visibility** | `visibility` | Filter by public/private visibility |
+| **User** | `created_by_me`, `modified_by_me`, `created_by__username`, `created_by__username__icontains` | Filter by user |
+| **Pagination** | `page`, `pageSize` | Paginate results |
+| **Sorting** | `ordering` | Sort results (e.g., "-created_at") |
+
+---
+
 ## Quick Reference
 
 | Service | Import | Purpose |
@@ -700,12 +967,16 @@ All query-building services use method chaining:
 
 ```typescript
 // Database
+const db = new Database(taruviClient)
 await db.from("table").get("id").update(data).execute()
 await db.from("table").filter({ status: "active" }).execute()
+await db.from("table").create({ name: "New" }).execute()
 
 // Storage
-await storage.from("bucket").delete("path").execute()
+const storage = new Storage(taruviClient)
+await storage.from("bucket").delete(["path/to/file.pdf"]).execute()
 await storage.from("bucket").filter({ search: "query" }).execute()
+await storage.from("bucket").download("path/to/file.pdf").execute()
 ```
 
 **Always call `.execute()` at the end to run the query!**
@@ -730,4 +1001,4 @@ const client = new Client({
 
 ---
 
-**Generated from production code examples • Last updated: 2025-12-15**
+**Generated from production code examples • Last updated: 2025-12-17**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taruvi/sdk",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Taruvi SDK",
   "main": "src/index.ts",
   "type": "module",

package/src/lib/App/AppClient.ts

@@ -0,0 +1,24 @@
+import type { Client } from "../../client.js"
+
+export class App {
+
+    private client: Client
+    private urlParams: {}
+
+    constructor(client: Client, urlParams: {}, filters?: {}) {
+        this.client = client
+        this.urlParams = urlParams
+    }
+
+    roles() {
+        return new App(this.client, {...this.urlParams})
+    }
+
+    filter(filters: {}) {
+        return new App(this.client, { ...this.urlParams }, filters)
+    }
+
+    execute() {
+        
+    }
+}

package/src/lib/Database/DatabaseClient.ts

@@ -14,7 +14,7 @@ export class Database {
     private body: object | undefined
     private filters: DatabaseFilters | undefined
 
-    constructor(client: Client, urlParams: UrlParams, operation?: HttpMethod | undefined, body?: object | undefined, filters?: DatabaseFilters) {
+    constructor(client: Client, urlParams: UrlParams = {}, operation?: HttpMethod | undefined, body?: object | undefined, filters?: DatabaseFilters) {
         this.client = client
         this.urlParams = urlParams
         this.operation = operation
@@ -40,7 +40,7 @@ export class Database {
     }
 
     update(body: any): Database {
-        return new Database(this.client, this.urlParams = { ...this.urlParams }, HttpMethod.PUT, body)
+        return new Database(this.client, this.urlParams = { ...this.urlParams }, HttpMethod.PATCH, body)
     }
 
     delete(recordId?: any): Database {
@@ -67,7 +67,6 @@ export class Database {
     async execute() {
         // Build the API URL
         const url = this.buildRoute()
-        // const fullUrl = `sites/eox_site/${url}` //remove for productions because baseurl is in the appscope, no need for site
 
         const operation = this.operation || HttpMethod.GET
 
@@ -75,11 +74,11 @@ export class Database {
             case HttpMethod.POST:
                 return await this.client.httpClient.post(url, this.body)
 
-            case HttpMethod.PUT:
+            case HttpMethod.PATCH:
                 if (!this.urlParams.recordId) {
-                    throw new Error('PUT operation requires a record ID. Use .get(recordId) before .update()')
+                    throw new Error('PATCH operation requires a record ID.')
                 }
-                return await this.client.httpClient.put(url, this.body)
+                return await this.client.httpClient.patch(url, this.body)
 
             case HttpMethod.DELETE:
                 return await this.client.httpClient.delete(url)

package/src/lib/Storage/StorageClient.ts

@@ -15,7 +15,7 @@ export class Storage {
     private filters: StorageFilters | undefined
 
 
-    constructor(client: Client, urlParams: BucketUrlParams, operation?: HttpMethod | undefined, body?: object, filters?: StorageFilters) {
+    constructor(client: Client, urlParams: BucketUrlParams = {} as BucketUrlParams, operation?: HttpMethod | undefined, body?: object, filters?: StorageFilters) {
         this.client = client
         this.urlParams = urlParams
         this.operation = operation