nexus-platform-sdk 0.1.0

package/README.md

@@ -0,0 +1,329 @@
+# Nexus Platform SDK
+
+The Nexus Platform SDK provides a JavaScript/TypeScript interface for building apps on the Nexus Platform. When Nexus generates your app via Code Studio, the generated code uses this SDK to authenticate users, manage your app's data, and execute serverless functions. You can use the same SDK to modify and extend your app.
+
+## Modules
+
+The SDK provides access to Nexus Platform's functionality through the following modules:
+
+- **`auth`**: Manage user authentication, registration, and session handling.
+- **`entities`**: Work with your app's data entities using CRUD operations.
+- **`functions`**: Execute serverless backend functions.
+
+## Installation
+
+```bash
+npm install nexus-platform-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from 'nexus-platform-sdk';
+
+const nexus = createClient({
+  appId: 'your-app-id',
+  tenantId: 'your-tenant-id',
+  dataSourceId: 'your-datasource-id',
+  apiUrl: 'https://api.nexus.io',
+});
+```
+
+## Example
+
+Here's a quick look at working with data in the SDK, using the `entities` module to create, update, and list records. In this example, we're working with a custom `Task` entity:
+
+```typescript
+import { nexus } from '@/api/nexusClient';
+
+// Create a new task
+const newTask = await nexus.entities.Task.create({
+  title: 'Complete project documentation',
+  status: 'pending',
+  dueDate: '2025-12-31',
+});
+
+// Update the task
+await nexus.entities.Task.update(newTask.id, {
+  status: 'in-progress',
+});
+
+// List all tasks sorted by creation date
+const tasks = await nexus.entities.Task.list('-created_at', 10);
+
+// Filter tasks by status
+const pendingTasks = await nexus.entities.Task.filter({ status: 'pending' });
+```
+
+## Authentication
+
+The SDK manages authentication state automatically, persisting tokens in localStorage.
+
+```typescript
+// Sign up a new user (auto-logs in after registration)
+const user = await nexus.auth.signUp({
+  email: 'user@example.com',
+  password: 'password123',
+  name: 'John Doe',
+});
+
+// Sign in existing user
+await nexus.auth.signIn({
+  email: 'user@example.com',
+  password: 'password123',
+});
+
+// Check authentication state
+if (nexus.auth.isAuthenticated) {
+  console.log('Logged in as:', nexus.auth.currentUser?.email);
+}
+
+// Get fresh user data from server
+const currentUser = await nexus.auth.me();
+
+// Validate token with server
+const isValid = await nexus.auth.checkAuth();
+
+// Listen for auth state changes
+const unsubscribe = nexus.auth.onAuthStateChange((user) => {
+  console.log(user ? 'Logged in' : 'Logged out');
+});
+
+// Sign out
+nexus.auth.signOut();
+
+// Or sign out with redirect
+nexus.auth.logout('/goodbye');
+
+// Redirect unauthenticated users to login
+nexus.auth.redirectToLogin('/dashboard');
+// Redirects to: /login?returnUrl=%2Fdashboard
+```
+
+## Entities
+
+The `entities` module provides dynamic access to your database tables with full CRUD support.
+
+### Listing and Filtering
+
+```typescript
+// Simple list
+const tasks = await nexus.entities.Task.list();
+
+// With positional parameters: sort, limit, skip, fields
+const tasks = await nexus.entities.Task.list('-created_at', 10, 0);
+
+// Or with options object
+const tasks = await nexus.entities.Task.list({
+  sort: '-created_at',  // prefix with '-' for descending
+  limit: 10,
+  skip: 0,
+  fields: ['id', 'title', 'status'],
+});
+
+// Filter by criteria
+const doneTasks = await nexus.entities.Task.filter({ status: 'done' });
+
+// Filter with sorting and pagination
+const tasks = await nexus.entities.Task.filter(
+  { status: 'pending' },
+  '-priority',  // sort
+  10,           // limit
+  0             // skip
+);
+```
+
+### CRUD Operations
+
+```typescript
+// Get single record by ID
+const task = await nexus.entities.Task.get('task-id');
+
+// Create new record
+const newTask = await nexus.entities.Task.create({
+  title: 'New Task',
+  status: 'pending',
+});
+
+// Update existing record
+const updated = await nexus.entities.Task.update(newTask.id, {
+  status: 'completed',
+});
+
+// Delete single record
+await nexus.entities.Task.delete(newTask.id);
+
+// Delete multiple records matching criteria
+const result = await nexus.entities.Task.deleteMany({ status: 'archived' });
+console.log(`Deleted ${result.deleted} records`);
+
+// Bulk create multiple records
+const tasks = await nexus.entities.Task.bulkCreate([
+  { title: 'Task 1', status: 'pending' },
+  { title: 'Task 2', status: 'pending' },
+  { title: 'Task 3', status: 'pending' },
+]);
+```
+
+### TypeScript Support
+
+Define interfaces for type-safe entity access:
+
+```typescript
+interface Task {
+  id: string;
+  title: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  priority: number;
+  created_at: string;
+}
+
+// Get typed table accessor
+const tasks = nexus.entities.getTable<Task>('Task');
+
+// Now all operations are fully typed
+const pending = await tasks.filter({ status: 'pending' });
+pending.forEach((task) => {
+  console.log(task.title);  // TypeScript knows this is a string
+  console.log(task.priority);  // TypeScript knows this is a number
+});
+```
+
+## Functions
+
+The `functions` module allows you to execute serverless backend functions.
+
+```typescript
+// Invoke a function
+const result = await nexus.functions.invoke('sendEmail', {
+  to: 'user@example.com',
+  subject: 'Hello from Nexus',
+  body: 'Welcome to the platform!',
+});
+
+// With full type safety
+interface EmailInput {
+  to: string;
+  subject: string;
+  body: string;
+}
+
+interface EmailOutput {
+  messageId: string;
+  status: 'sent' | 'queued';
+}
+
+const result = await nexus.functions.invoke<EmailInput, EmailOutput>('sendEmail', {
+  to: 'user@example.com',
+  subject: 'Hello',
+  body: 'Welcome!',
+});
+
+console.log(result.messageId);  // Fully typed
+
+// List available functions
+const functions = await nexus.functions.list();
+functions.forEach((fn) => {
+  console.log(`${fn.name}: ${fn.description}`);
+});
+```
+
+## Error Handling
+
+The SDK throws `NexusApiError` for all API errors, providing structured error information:
+
+```typescript
+import { NexusApiError } from 'nexus-platform-sdk';
+
+try {
+  await nexus.entities.Task.get('non-existent-id');
+} catch (error) {
+  if (error instanceof NexusApiError) {
+    console.error('Status:', error.status);      // HTTP status code
+    console.error('Message:', error.message);    // Error message
+    console.error('Code:', error.code);          // Application error code
+    console.error('Details:', error.details);    // Additional error details
+  }
+}
+```
+
+## React Integration
+
+Here's a recommended pattern for integrating the SDK with React applications:
+
+```typescript
+// src/api/nexusClient.ts
+import { createClient } from 'nexus-platform-sdk';
+
+export const nexus = createClient({
+  appId: import.meta.env.VITE_NEXUS_APP_ID,
+  tenantId: import.meta.env.VITE_NEXUS_TENANT_ID,
+  dataSourceId: import.meta.env.VITE_NEXUS_DATASOURCE_ID,
+  apiUrl: import.meta.env.VITE_NEXUS_API_URL,
+});
+
+// src/hooks/useAuth.ts
+import { useEffect, useState } from 'react';
+import { nexus } from '../api/nexusClient';
+import type { User } from 'nexus-platform-sdk';
+
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(nexus.auth.currentUser);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Validate token on mount
+    nexus.auth.checkAuth().finally(() => setLoading(false));
+
+    // Subscribe to auth state changes
+    return nexus.auth.onAuthStateChange(setUser);
+  }, []);
+
+  return {
+    user,
+    loading,
+    isAuthenticated: !!user,
+    signIn: nexus.auth.signIn.bind(nexus.auth),
+    signUp: nexus.auth.signUp.bind(nexus.auth),
+    signOut: nexus.auth.signOut.bind(nexus.auth),
+  };
+}
+
+// src/components/ProtectedRoute.tsx
+import { Navigate, useLocation } from 'react-router-dom';
+import { useAuth } from '../hooks/useAuth';
+
+export function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated, loading } = useAuth();
+  const location = useLocation();
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!isAuthenticated) {
+    return <Navigate to={`/login?returnUrl=${location.pathname}`} replace />;
+  }
+
+  return <>{children}</>;
+}
+```
+
+## Development
+
+### Build the SDK
+
+```bash
+npm install
+npm run build
+```
+
+### Run tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT