@blinkdotnew/sdk 0.14.9 → 0.14.11

package/README.md

@@ -35,8 +35,8 @@ const user = await blink.auth.me()
 
 // Database operations (zero config)
 const todos = await blink.db.todos.list({
-  where: { user_id: user.id },
-  orderBy: { created_at: 'desc' },
+  where: { userId: user.id },
+  orderBy: { createdAt: 'desc' },
   limit: 20
 })
 
@@ -187,9 +187,13 @@ await blink.auth.updateMe({ displayName: 'New Name' })
 blink.auth.setToken(jwt, persist?)
 const isAuth = blink.auth.isAuthenticated()
 
-// Auth state listener
+// Auth state listener (REQUIRED for React apps!)
 const unsubscribe = blink.auth.onAuthStateChanged((state) => {
   console.log('Auth state:', state)
+  // state.user - current user or null
+  // state.isLoading - true while auth is initializing
+  // state.isAuthenticated - true if user is logged in
+  // state.tokens - current auth tokens
 })
 ```
 
@@ -201,6 +205,11 @@ The SDK now automatically converts between JavaScript camelCase and SQL snake_ca
 - **Stored as snake_case**: `user_id`, `created_at`, `is_completed`
 - **No manual conversion needed!**
 
+**⚠️ Important: Always Use camelCase in Your Code**
+- ✅ **Correct**: `{ userId: user.id, createdAt: new Date() }`
+- ❌ **Wrong**: `{ user_id: user.id, created_at: new Date() }`
+- **Exception**: Raw SQL queries still use snake_case (as stored in database)
+
 ```typescript
 // Create (ID auto-generated if not provided)
 const todo = await blink.db.todos.create({
@@ -226,23 +235,23 @@ const todos = await blink.db.todos.list({
 
 // Note: Boolean fields are returned as "0"/"1" strings from SQLite
 // Check boolean values using Number(value) > 0
-const completedTodos = todos.filter(todo => Number(todo.completed) > 0)
-const incompleteTodos = todos.filter(todo => Number(todo.completed) === 0)
+const completedTodos = todos.filter(todo => Number(todo.isCompleted) > 0)
+const incompleteTodos = todos.filter(todo => Number(todo.isCompleted) === 0)
 
 // Update
-await blink.db.todos.update(todo.id, { completed: true })
+await blink.db.todos.update(todo.id, { isCompleted: true })
 
 // Delete
 await blink.db.todos.delete(todo.id)
 
 // Bulk operations (IDs auto-generated if not provided)
 await blink.db.todos.createMany([
-  { title: 'Task 1', user_id: user.id }, // ID will be auto-generated
-  { id: 'custom_id', title: 'Task 2', user_id: user.id } // Custom ID provided
+  { title: 'Task 1', userId: user.id }, // ID will be auto-generated
+  { id: 'custom_id', title: 'Task 2', userId: user.id } // Custom ID provided
 ])
 await blink.db.todos.upsertMany([...])
 
-// Raw SQL
+// Raw SQL (note: raw SQL still uses snake_case as stored in database)
 const result = await blink.db.sql('SELECT * FROM todos WHERE user_id = ?', [user.id])
 ```
 
@@ -1205,9 +1214,9 @@ The SDK is written in TypeScript and provides full type safety:
 interface Todo {
   id: string
   title: string
-  completed: boolean  // Will be returned as "0" or "1" string from SQLite
-  user_id: string
-  created_at: string
+  isCompleted: boolean  // Will be returned as "0" or "1" string from SQLite
+  userId: string        // Automatically converted from snake_case user_id
+  createdAt: string     // Automatically converted from snake_case created_at
 }
 
 // Note: Boolean fields are returned as "0"/"1" strings from SQLite
@@ -1215,12 +1224,12 @@ interface Todo {
 const todos = await blink.db.todos.list<Todo>()
 
 // Check boolean values properly
-const completedTodos = todos.filter(todo => Number(todo.completed) > 0)
-const incompleteTodos = todos.filter(todo => Number(todo.completed) === 0)
+const completedTodos = todos.filter(todo => Number(todo.isCompleted) > 0)
+const incompleteTodos = todos.filter(todo => Number(todo.isCompleted) === 0)
 
 // When filtering by boolean values in queries, use "0"/"1" strings
 const onlyCompleted = await blink.db.todos.list<Todo>({
-  where: { completed: "1" }  // Use string "1" for true, "0" for false
+  where: { isCompleted: "1" }  // Use string "1" for true, "0" for false
 })
 // todos is fully typed as Todo[]
 ```
@@ -1390,6 +1399,44 @@ function MyRealtimeComponent() {
 
 ### React
 
+**⚠️ Critical: Always Use Auth State Listener, Never One-Time Checks**
+
+The most common authentication mistake is checking auth status once instead of listening to changes:
+
+```typescript
+// ❌ WRONG - One-time check misses auth completion
+useEffect(() => {
+  const checkAuth = async () => {
+    try {
+      const userData = await blink.auth.me()
+      setUser(userData)
+    } catch (error) {
+      console.error('Auth check failed:', error)
+    } finally {
+      setLoading(false)
+    }
+  }
+  checkAuth() // Only runs once - misses when auth completes later!
+}, [])
+
+// ✅ CORRECT - Listen to auth state changes
+useEffect(() => {
+  const unsubscribe = blink.auth.onAuthStateChanged((state) => {
+    setUser(state.user)
+    setLoading(state.isLoading)
+  })
+  return unsubscribe
+}, [])
+```
+
+**Why the one-time check fails:**
+1. App loads → `blink.auth.me()` called immediately
+2. Auth still initializing → Call fails, user set to `null`
+3. Auth completes later → App never knows because it only checked once
+4. User stuck on "Please sign in" screen forever
+
+**Always use `onAuthStateChanged()` for React apps!**
+
 ```typescript
 import { createClient } from '@blinkdotnew/sdk'
 import { useState, useEffect } from 'react'
@@ -1398,19 +1445,46 @@ const blink = createClient({ projectId: 'your-project', authRequired: true })
 
 function App() {
   const [user, setUser] = useState(null)
+  const [loading, setLoading] = useState(true)
 
   useEffect(() => {
     const unsubscribe = blink.auth.onAuthStateChanged((state) => {
       setUser(state.user)
+      setLoading(state.isLoading)
     })
     return unsubscribe
   }, [])
 
+  if (loading) return <div>Loading...</div>
   if (!user) return <div>Please log in</div>
 
   return <div>Welcome, {user.email}!</div>
 }
 
+// ❌ WRONG - One-time auth check (misses auth state changes)
+function BadApp() {
+  const [user, setUser] = useState(null)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    const checkAuth = async () => {
+      try {
+        const userData = await blink.auth.me()
+        setUser(userData)
+      } catch (error) {
+        console.error('Auth check failed:', error)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    checkAuth() // ❌ Only runs once - misses when auth completes later!
+  }, [])
+
+  // This pattern causes users to get stuck on "Please sign in" 
+  // even after authentication completes
+}
+
 // React example with search functionality
 function SearchResults() {
   const [query, setQuery] = useState('')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinkdotnew/sdk",
-  "version": "0.14.9",
+  "version": "0.14.11",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",