@aerostack/sdk-react 0.6.6

package/.tshy/build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "../src",
+    "module": "nodenext",
+    "moduleResolution": "nodenext"
+  }
+}

package/.tshy/commonjs.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./build.json",
+  "include": [
+    "../src/**/*.ts",
+    "../src/**/*.cts",
+    "../src/**/*.tsx",
+    "../src/**/*.json"
+  ],
+  "exclude": [
+    "../src/**/*.mts",
+    "../src/package.json"
+  ],
+  "compilerOptions": {
+    "outDir": "../.tshy-build/commonjs"
+  }
+}

package/.tshy/esm.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./build.json",
+  "include": [
+    "../src/**/*.ts",
+    "../src/**/*.mts",
+    "../src/**/*.tsx",
+    "../src/**/*.json"
+  ],
+  "exclude": [
+    "../src/package.json"
+  ],
+  "compilerOptions": {
+    "outDir": "../.tshy-build/esm"
+  }
+}

package/README.md

@@ -0,0 +1,137 @@
+# @aerostack/react
+
+The official React SDK for Aerostack. Easily integrate authentication, database, AI, and other Aerostack services into your React applications using idiomatic Hooks.
+
+## Installation
+
+```bash
+npm install @aerostack/react
+# or
+yarn add @aerostack/react
+# or
+pnpm add @aerostack/react
+```
+
+## Usage
+
+### 1. Wrap your app in `AerostackProvider`
+
+```tsx
+import { AerostackProvider } from '@aerostack/react';
+
+function App() {
+  return (
+    <AerostackProvider 
+      projectUrl="https://your-project.aerostack.dev" 
+      apiKey="your-public-api-key"
+    >
+      <YourComponent />
+    </AerostackProvider>
+  );
+}
+```
+
+### 2. Use Hooks
+
+#### Authentication
+
+```tsx
+import { useAuth } from '@aerostack/react';
+
+function LoginButton() {
+  const { signIn, user, isLoading } = useAuth();
+
+  if (user) return <div>Welcome, {user.email}</div>;
+
+  return (
+    <button onClick={() => signIn('email', 'password')}>
+      {isLoading ? 'Loading...' : 'Sign In'}
+    </button>
+  );
+}
+```
+
+#### Database
+
+```tsx
+import { useDb } from '@aerostack/react';
+
+function TodoList() {
+  const { data: todos, isLoading } = useDb('todos').find();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <ul>
+      {todos.map(todo => <li key={todo.id}>{todo.title}</li>)}
+    </ul>
+  );
+}
+```
+
+#### AI Chat
+
+```tsx
+import { useAI } from '@aerostack/react';
+
+function ChatBot() {
+  const { messages, sendMessage } = useAI('support-agent');
+
+  return (
+    <div>
+      {messages.map(m => <div>{m.content}</div>)}
+      <button onClick={() => sendMessage("Hello!")}>Say Hi</button>
+    </div>
+  );
+  );
+}
+```
+
+## SSR and Backend Integration
+
+### Client-Side Only (SPA)
+This SDK is designed for **client-side React apps**. Hooks like `useAuth()` run in the browser.
+
+### Server-Side Rendering (Next.js, Remix)
+For SSR frameworks, use different approaches for server vs. client:
+
+**Server-side (data fetching, API routes)**:
+```tsx
+// app/api/users/route.ts (Next.js App Router)
+import { SDK } from '@aerostack/node';
+
+export async function GET() {
+  const sdk = new SDK({ apiKeyAuth: process.env.AEROSTACK_API_KEY });
+  const users = await sdk.database.dbQuery({
+    sql: 'SELECT * FROM users'
+  });
+  return Response.json(users);
+}
+```
+
+**Client-side (React components)**:
+```tsx
+'use client'; // Next.js 13+
+import { AerostackProvider, useAuth } from '@aerostack/react';
+
+function ClientComponent() {
+  const { user } = useAuth();
+  return <div>{user?.email}</div>;
+}
+```
+
+### Backend Worker Pattern
+If building Cloudflare Workers that need both client Auth and server bindings:
+```typescript
+import { AerostackClient, AerostackServer } from '@aerostack/sdk';
+
+// Use both SDKs as needed
+const client = new AerostackClient({ projectSlug: "my-project" });
+const server = new AerostackServer(env);
+```
+
+See [`@aerostack/sdk` documentation](../sdk/README.md#backend-wrapper-pattern) for details.
+
+## Documentation
+
+For full documentation, visit [docs.aerostack.dev](https://docs.aerostack.dev/sdk/react).

package/examples/README.md

@@ -0,0 +1,27 @@
+# @aerostack/react Examples
+
+Examples for `@aerostack/react`.
+
+## Prerequisites
+
+```bash
+npm install @aerostack/react @aerostack/sdk
+```
+
+## Available Examples
+
+| Example | Description | Pattern |
+|---------|-------------|---------|
+| [**Basic Auth App**](./basic-auth-app.tsx) | Complete Login/Logout flow using `useAuth`. | Client-Side |
+| [**Protected Routes**](./protected-routes.tsx) | Wrapper component for React Router. | Routing |
+| [**Next.js App Router**](./next-app-router.tsx) | Server Components integration pattern. | Next.js 13+ |
+
+## Config
+
+Wrap your app root:
+
+```tsx
+<AerostackProvider projectSlug="my-app">
+  <App />
+</AerostackProvider>
+```

package/examples/basic-auth-app.tsx

@@ -0,0 +1,64 @@
+import React, { useState } from 'react';
+import { AerostackProvider, useAuth } from '@aerostack/react';
+
+/**
+ * Basic Auth App Example
+ * 
+ * Demonstrates basic usage of AerostackProvider and useAuth hook.
+ */
+
+// 1. Root Component wraps app in Provider
+export default function App() {
+    return (
+        <AerostackProvider
+            projectSlug="YOUR_PROJECT_SLUG"
+        // baseUrl="https://api.aerostack.ai/v1" // Optional
+        >
+            <AuthDemo />
+        </AerostackProvider>
+    );
+}
+
+// 2. Child Component uses hooks
+function AuthDemo() {
+    const { user, login, logout, isLoading, error } = useAuth();
+    const [email, setEmail] = useState('');
+    const [password, setPassword] = useState('');
+
+    if (isLoading) return <div>Loading...</div>;
+
+    if (user) {
+        return (
+            <div>
+                <h1>Welcome, {user.name || user.email}!</h1>
+                <button onClick={() => logout()}>Logout</button>
+            </div>
+        );
+    }
+
+    return (
+        <div>
+            <h1>Login</h1>
+            {error && <div style={{ color: 'red' }}>{error.message}</div>}
+
+            <form onSubmit={(e) => {
+                e.preventDefault();
+                login(email, password);
+            }}>
+                <input
+                    type="email"
+                    placeholder="Email"
+                    value={email}
+                    onChange={e => setEmail(e.target.value)}
+                />
+                <input
+                    type="password"
+                    placeholder="Password"
+                    value={password}
+                    onChange={e => setPassword(e.target.value)}
+                />
+                <button type="submit">Login</button>
+            </form>
+        </div>
+    );
+}

package/examples/next-app-router.tsx

@@ -0,0 +1,55 @@
+/**
+ * Next.js App Router Example
+ * 
+ * Demonstrates how to access user session in Server Components.
+ * Note: @aerostack/react is primarily for Client Components.
+ * For Server Components, usage depends on where you store the token (cookies vs local storage).
+ * 
+ * If using cookies:
+ */
+
+// app/layout.tsx (Client Component Wrapper)
+/*
+'use client';
+import { AerostackProvider } from '@aerostack/react';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AerostackProvider projectSlug="...">
+          {children}
+        </AerostackProvider>
+      </body>
+    </html>
+  );
+}
+*/
+
+// app/page.tsx (Server Component)
+import { cookies } from 'next/headers';
+import { AerostackClient } from '@aerostack/sdk'; // Use Core SDK on server
+
+async function getUser() {
+    const cookieStore = cookies();
+    const token = cookieStore.get('auth_token')?.value;
+
+    if (!token) return null;
+
+    const client = new AerostackClient({ projectSlug: '...' });
+    try {
+        return await client.auth.getCurrentUser(token);
+    } catch {
+        return null;
+    }
+}
+
+export default async function Page() {
+    const user = await getUser();
+
+    if (!user) {
+        return <div>Please log in</div>
+    }
+
+    return <h1>Hello Server-Side User: {user.email}</h1>
+}

package/examples/protected-routes.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+import { useAuth } from '@aerostack/react';
+// Assuming React Router usage
+import { Navigate, Outlet } from 'react-router-dom';
+
+/**
+ * Protected Route Example
+ * 
+ * Demonstrates a reusable ProtectedRoute component.
+ */
+
+export const ProtectedRoute = () => {
+    const { user, isLoading } = useAuth();
+
+    if (isLoading) {
+        return <div>Loading authentication...</div>;
+    }
+
+    if (!user) {
+        // Redirect to login if not authenticated
+        return <Navigate to="/login" replace />;
+    }
+
+    // Render child routes if authenticated
+    return <Outlet />;
+};
+
+// Usage in App.tsx:
+/*
+<Routes>
+  <Route path="/login" element={<LoginPage />} />
+  
+  <Route element={<ProtectedRoute />}>
+    <Route path="/dashboard" element={<DashboardPage />} />
+    <Route path="/profile" element={<ProfilePage />} />
+  </Route>
+</Routes>
+*/

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@aerostack/sdk-react",
+  "version": "0.6.6",
+  "author": "Aerostack",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aerostackdev/sdks.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/aerostackdev/sdks/issues"
+  },
+  "homepage": "https://docs.aerostack.dev",
+  "tshy": {
+    "exports": {
+      ".": "./src/index.ts",
+      "./package.json": "./package.json"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tshy",
+    "lint": "eslint --cache --max-warnings=0 src",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.26.0",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@types/react-dom": "^18.0.0 || ^19.0.0",
+    "eslint": "^9.26.0",
+    "globals": "^15.14.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tshy": "^2.0.0",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.26.0"
+  },
+  "dependencies": {
+    "@aerostack/sdk-web": "^0.6.6"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts",
+  "module": "./dist/esm/index.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/context.tsx

@@ -0,0 +1,52 @@
+import React, { createContext, useContext, useMemo } from 'react';
+import { SDK } from '@aerostack/sdk-web';
+
+export interface AerostackContextType {
+    sdk: SDK;
+    projectId: string;
+}
+
+const AerostackContext = createContext<AerostackContextType | null>(null);
+
+export interface AerostackProviderProps {
+    projectId: string;
+    baseUrl?: string;
+    children: React.ReactNode;
+}
+
+export const AerostackProvider: React.FC<AerostackProviderProps> = ({
+    projectId,
+    baseUrl = 'https://api.aerostack.ai/v1',
+    children,
+}) => {
+    const sdk = useMemo(() => {
+        // In web context, we use the hook registration for projectId parity
+        import('@aerostack/sdk-web').then(mod => {
+            // @ts-ignore - the hook logic handles this
+            if (mod.setProjectId) mod.setProjectId(projectId);
+        });
+
+        return new SDK({
+            serverURL: baseUrl,
+        });
+    }, [baseUrl, projectId]);
+
+    const value = useMemo(() => ({
+        sdk,
+        projectId,
+    }), [sdk, projectId]);
+
+    return (
+        <AerostackContext.Provider value={value}>
+            {children}
+        </AerostackContext.Provider>
+    );
+};
+
+export const useAerostack = () => {
+    const context = useContext(AerostackContext);
+    if (!context) {
+        throw new Error('useAerostack must be used within an AerostackProvider');
+    }
+    return context;
+};

package/src/hooks/useAI.ts

@@ -0,0 +1,37 @@
+import { useState, useCallback } from 'react';
+import { useAerostack } from '../context.js';
+
+export interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+
+export const useAI = () => {
+    const { sdk } = useAerostack();
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    const chat = useCallback(async (messages: ChatMessage[], options?: any) => {
+        try {
+            setLoading(true);
+            setError(null);
+            const result = await sdk.ai.aiChat({
+                messages,
+                ...options,
+            });
+            return result.response;
+        } catch (err) {
+            const error = err instanceof Error ? err : new Error('AI chat failed');
+            setError(error);
+            throw error;
+        } finally {
+            setLoading(false);
+        }
+    }, [sdk]);
+
+    return {
+        chat,
+        loading,
+        error,
+    };
+};

package/src/hooks/useAuth.ts

@@ -0,0 +1,59 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useAerostack } from '../context.js';
+
+export interface User {
+    id: string;
+    email: string;
+    name?: string;
+    [key: string]: any;
+}
+
+export const useAuth = () => {
+    const { sdk } = useAerostack();
+    const [user, setUser] = useState<User | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+
+    const refreshUser = useCallback(async () => {
+        try {
+            setLoading(true);
+            // Logic to fetch current user session from sdk.authentication
+            // const session = await sdk.authentication.getSession();
+            // setUser(session.user);
+        } catch (err) {
+            setError(err instanceof Error ? err : new Error('Failed to fetch user'));
+        } finally {
+            setLoading(false);
+        }
+    }, [sdk]);
+
+    useEffect(() => {
+        refreshUser();
+    }, [refreshUser]);
+
+    const signIn = async (credentials: any) => {
+        const result = await sdk.authentication.authSignin(credentials);
+        // setUser(result.user);
+        return result;
+    };
+
+    const signUp = async (credentials: any) => {
+        const result = await sdk.authentication.authSignup(credentials);
+        return result;
+    };
+
+    const signOut = async () => {
+        // await sdk.authentication.signOut();
+        setUser(null);
+    };
+
+    return {
+        user,
+        loading,
+        error,
+        signIn,
+        signUp,
+        signOut,
+        refreshUser,
+    };
+};

package/src/hooks/useCache.ts

@@ -0,0 +1,44 @@
+import { useState, useCallback } from 'react';
+import { useAerostack } from '../context.js';
+
+export const useCache = () => {
+    const { sdk } = useAerostack();
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    const get = useCallback(async (key: string) => {
+        try {
+            setLoading(true);
+            setError(null);
+            const result = await sdk.cache.cacheGet({ key });
+            return result.value;
+        } catch (err) {
+            const error = err instanceof Error ? err : new Error('Cache get failed');
+            setError(error);
+            throw error;
+        } finally {
+            setLoading(false);
+        }
+    }, [sdk]);
+
+    const set = useCallback(async (key: string, value: any, ttl?: number) => {
+        try {
+            setLoading(true);
+            setError(null);
+            await sdk.cache.cacheSet({ key, value, ttl });
+        } catch (err) {
+            const error = err instanceof Error ? err : new Error('Cache set failed');
+            setError(error);
+            throw error;
+        } finally {
+            setLoading(false);
+        }
+    }, [sdk]);
+
+    return {
+        get,
+        set,
+        loading,
+        error,
+    };
+};

package/src/hooks/useDb.ts

@@ -0,0 +1,31 @@
+import { useState, useCallback } from 'react';
+import { useAerostack } from '../context.js';
+
+export const useDb = () => {
+    const { sdk } = useAerostack();
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+
+    const query = useCallback(async (sql: string, params?: any[]) => {
+        try {
+            setLoading(true);
+            setError(null);
+            const result = await sdk.database.dbQuery({
+                requestBody: { sql, params }
+            });
+            return result; // result is already DBQueryResult
+        } catch (err) {
+            const error = err instanceof Error ? err : new Error('Database query failed');
+            setError(error);
+            throw error;
+        } finally {
+            setLoading(false);
+        }
+    }, [sdk]);
+
+    return {
+        query,
+        loading,
+        error,
+    };
+};

package/src/hooks/useSubscription.ts

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react';
+import { useAerostack } from '../context.js';
+export interface RealtimeSubscriptionOptions {
+    event?: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+    filter?: Record<string, any>;
+}
+
+/**
+ * Hook to subscribe to Aerostack realtime events
+ * 
+ * @param topic The topic to subscribe to (e.g., 'posts' or 'table/posts/projectId')
+ * @param options Event type and filtering options
+ */
+export function useSubscription<T = any>(
+    topic: string,
+    options: RealtimeSubscriptionOptions = {}
+) {
+    const { sdk } = useAerostack();
+    const [data, setData] = useState<T | null>(null);
+    const [error, setError] = useState<Error | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        let isMounted = true;
+        const realtime = (sdk as any).realtime;
+
+        if (!realtime) {
+            setError(new Error('Realtime not supported in this SDK version'));
+            setLoading(false);
+            return;
+        }
+
+        const channel = realtime.channel(topic, options);
+
+        const setup = async () => {
+            try {
+                await realtime.connect();
+
+                channel.on('*', (payload: any) => {
+                    if (isMounted) {
+                        setData(payload);
+                    }
+                });
+
+                channel.subscribe();
+                setLoading(false);
+            } catch (err: any) {
+                if (isMounted) {
+                    setError(err);
+                    setLoading(false);
+                }
+            }
+        };
+
+        setup();
+
+        return () => {
+            isMounted = false;
+            // Note: We don't automatically disconnect the global client,
+            // but we could unsubscribe from the channel if needed.
+            // channel.unsubscribe();
+        };
+    }, [sdk, topic, JSON.stringify(options)]);
+
+    return { data, error, loading };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from './context.js';
+export * from './hooks/useAuth.js';
+export * from './hooks/useDb.js';
+export * from './hooks/useAI.js';
+export * from './hooks/useCache.js';
+
+// Re-export core types and client for convenience
+import { SDK, SDKOptions } from '@aerostack/sdk-web';
+
+export type { SDK };
+export const AerostackClient = SDK;
+export type AerostackClient = SDK;
+export type AerostackConfig = SDKOptions;
+
+/** @deprecated Use AerostackClient instead. */
+export const AerocallClient = SDK;
+/** @deprecated Use AerostackClient instead. */
+export type AerocallClient = SDK;
+/** @deprecated Use AerostackConfig instead. */
+export type AerocallConfig = SDKOptions;

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+    "compilerOptions": {
+        "incremental": false,
+        "target": "ES2020",
+        "lib": [
+            "ES2022",
+            "DOM",
+            "DOM.Iterable"
+        ],
+        "jsx": "react-jsx",
+        "module": "Node16",
+        "moduleResolution": "Node16",
+        "allowJs": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "outDir": ".",
+        "strict": true,
+        "isolatedModules": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src"
+    ],
+    "exclude": [
+        "node_modules"
+    ]
+}