npm package: @nexushub/client
Description: The God-Tier NexusHub SDK
Author: Jom Irish - NexusHub
Latest version: 0.0.1

# NexusHub Client SDK

<div align="center">

[![npm version](https://img.shields.io/npm/v/@nexushub/client.svg?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@nexushub/client)
[![bundle size](https://img.shields.io/bundlephobia/minzip/@nexushub/client?style=for-the-badge&label=size)](https://bundlephobia.com/package/@nexushub/client)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18%2B%2F19-blue?style=for-the-badge&logo=react)](https://reactjs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)

**The God-Tier Headless CMS SDK** — Everything you need to build blazing-fast websites with real-time content, analytics, and authentication.

</div>

## ✨ Features

### 🚀 **Performance First**

- **Multi-layer caching**: Memory → LocalStorage → Remote with LRU eviction
- **Request optimization**: Batching, deduplication, exponential backoff
- **Smart preloading**: Automatic content prediction and prefetching
- **< 5ms** cache hits, **< 100ms** cold starts

### 📊 **Built-in Analytics Engine**

- **Real-time tracking**: Page views, clicks, form submissions
- **Web Vitals**: Core Web Vitals with RUM (Real User Monitoring)
- **Session management**: 30-minute sessions with automatic renewal
- **User identification**: Anonymous → Known user handshake
- **E-commerce ready**: Track purchases, cart events, conversions

### 🔐 **Authentication System**

- **Full auth flow**: Register, login, logout, social login (Google)
- **Protected routes**: React hooks for auth state
- **Session persistence**: HttpOnly cookies for security
- **Role-based access**: User roles and permissions

### 📁 **Content Engine**

- **Type-safe content**: Full TypeScript support with generics
- **Advanced querying**: Filter, sort, paginate, search, include
- **Real-time updates**: WebSocket/SSE subscriptions
- **Collection support**: Dynamic content with rich relationships
- **Singleton pages**: Static content with smart caching

### 🛠 **Developer Experience**

- **Zero-config setup**: Auto-detects environment variables
- **Local development**: Offline mode with local cache
- **CLI tool**: Pull, seed, deploy, and manage content
- **Debug mode**: Detailed logs and performance metrics
- **Hot reload**: Instant updates during development

## 🚀 Quick Start

### 1. Installation

```bash
npm install @nexushub/client
# or
yarn add @nexushub/client
# or
pnpm add @nexushub/client
```

### 2. Environment Setup

Create `.env.local` in your project root:

```env
# Required
NEXT_PUBLIC_NEXUS_ID=your_project_id_here
NEXT_PUBLIC_NEXUS_KEY=your_api_key_here

# Optional (defaults to https://api.nexushub.com/v1)
NEXT_PUBLIC_NEXUS_API_URL=https://api.nexushub.com/v1
```

### 3. Wrap Your App (Next.js/React)

```tsx
// app/layout.tsx (Next.js App Router)
import { NexusProvider } from '@nexushub/client'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <NexusProvider>
          {children}
        </NexusProvider>
      </body>
    </html>
  )
}
```

### 4. Use Content Anywhere

```tsx
// app/page.tsx
import { nexus } from '@nexushub/client'

export default async function HomePage() {
  const homePage = await nexus.getPage('home')
  const blogPosts = await nexus.content.getCollection('blog_posts', {
    page: 1,
    limit: 10,
    sort: 'createdAt',
    order: 'desc',
    filter: { published: true }
  })

  return (
    <main>
      <h1>{homePage.title}</h1>
      <p>{homePage.content}</p>
      
      <h2>Latest Posts</h2>
      <ul>
        {blogPosts.items.map(post => (
          <li key={post.id}>
            <h3>{post.title}</h3>
            <p>{post.excerpt}</p>
          </li>
        ))}
      </ul>
    </main>
  )
}
```

## 📖 Documentation

### Table of Contents

1. [Configuration](#configuration)
2. [Content Fetching](#content-fetching)
3. [Authentication](#authentication)
4. [Analytics](#analytics)
5. [Caching](#caching)
6. [CLI Tool](#cli-tool)
7. [API Reference](#api-reference)
8. [Examples](#examples)
9. [Troubleshooting](#troubleshooting)

## 🔧 Configuration

### Auto Configuration (Recommended)

```typescript
// Uses environment variables automatically
const client = nexus // Singleton instance
```

### Manual Configuration

```typescript
import { createNexusClient } from '@nexushub/client'

const client = createNexusClient({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiUrl: 'https://api.nexushub.com/v1', // Optional
  debug: true, // Enable debug logging
  cacheStrategy: 'memory', // 'memory' | 'localStorage' | 'none'
  revalidateTime: 60, // Cache revalidation in seconds
  timeout: 10000, // Request timeout in ms
  retries: 3, // Number of retry attempts
})
```

### React Configuration

```tsx
// app/NexusWrapper.tsx
'use client'

import { NexusProvider } from '@nexushub/client'

export function NexusWrapper({ children }: { children: React.ReactNode }) {
  return (
    <NexusProvider projectId="optional-override-id">
      {children}
    </NexusProvider>
  )
}
```

## 📁 Content Fetching

### Get a Single Page

```typescript
// Basic usage
const page = await nexus.getPage('home')

// With options
const page = await nexus.getPage('about', {
  revalidate: 300, // Revalidate every 5 minutes
  tags: ['page:about'], // Cache tags for invalidation
  forceRefresh: false, // Bypass cache
  includeMetadata: true, // Include cache metadata
})
```

### Get Collections

```typescript
// Get all items from a collection
const posts = await nexus.content.getCollection('blog_posts')

// Advanced querying
const products = await nexus.content.getCollection('products', {
  page: 1,
  limit: 20,
  sort: 'price',
  order: 'asc',
  filter: {
    category: 'electronics',
    price: { $lt: 1000 },
    inStock: true
  },
  search: 'wireless headphones',
  fields: ['id', 'name', 'price', 'image'],
  include: ['category', 'reviews'],
})
```

### Get a Single Item

```typescript
const product = await nexus.content.getItem('products', 'prod_12345', {
  include: ['category', 'reviews', 'variants'],
  tags: ['product:prod_12345'],
})
```

### Search Across Collections

```typescript
const results = await nexus.content.search('wireless', {
  collections: ['products', 'articles'],
  fields: ['title', 'description', 'content'],
  limit: 50,
})
```

### Get Global Settings

```typescript
const globals = await nexus.content.getGlobals({
  include: ['navigation', 'footer', 'social_links'],
  revalidate: 3600, // Cache for 1 hour
})
```

## 🔐 Authentication

### Setup Auth Provider

```tsx
// app/auth/layout.tsx
'use client'

import { useNexusAuth } from '@nexushub/client'

export default function AuthLayout({ children }) {
  const { user, isLoading, isAuthenticated } = useNexusAuth()
  
  if (isLoading) return <div>Loading...</div>
  
  return (
    <div>
      {isAuthenticated ? (
        <div>
          <p>Welcome, {user.name}!</p>
          {children}
        </div>
      ) : (
        <LoginForm />
      )}
    </div>
  )
}
```

### Login/Register Forms

```tsx
'use client'

import { useNexusAuth } from '@nexushub/client'
import { useState } from 'react'

export function LoginForm() {
  const { login, register, loginWithGoogle } = useNexusAuth()
  const [email, setEmail] = useState('')
  const [password, setPassword] = useState('')
  
  const handleLogin = async () => {
    try {
      await login({ email, password })
      // Redirect or show success
    } catch (error) {
      console.error('Login failed:', error)
    }
  }
  
  const handleGoogleLogin = () => {
    loginWithGoogle()
  }
  
  return (
    <div>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
      />
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
      />
      <button onClick={handleLogin}>Login</button>
      <button onClick={handleGoogleLogin}>Login with Google</button>
    </div>
  )
}
```

### Protected Routes Hook

```tsx
'use client'

import { useNexusAuth } from '@nexushub/client'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

export function useRequireAuth(redirectTo = '/login') {
  const { user, isLoading, isAuthenticated } = useNexusAuth()
  const router = useRouter()
  
  useEffect(() => {
    if (!isLoading && !isAuthenticated) {
      router.push(redirectTo)
    }
  }, [isLoading, isAuthenticated, router, redirectTo])
  
  return { user, isLoading }
}

// Usage
export default function DashboardPage() {
  const { user, isLoading } = useRequireAuth('/login')
  
  if (isLoading) return <div>Loading...</div>
  
  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user.name}!</p>
    </div>
  )
}
```

## 📊 Analytics

### Automatic Tracking

Analytics starts automatically when you wrap your app with `NexusProvider`. It tracks:

- Page views and route changes
- Click events (links, buttons)
- Form submissions
- Web Vitals (CLS, LCP, FID, INP)
- Performance metrics
- Error tracking

### Manual Event Tracking

```typescript
import { nexus } from '@nexushub/client'

// Get analytics instance (automatically initialized)
const analytics = nexus['analytics'] // Internal access

// Or track custom events
analytics.track('button_clicked', {
  button_id: 'cta-primary',
  page: '/home',
  timestamp: new Date().toISOString()
})

// Track purchases
analytics.trackPurchase({
  order_id: 'ORD_12345',
  total: 99.99,
  currency: 'USD',
  items: [
    { id: 'prod_1', name: 'Product 1', price: 49.99, quantity: 2 }
  ]
})

// Identify users (link anonymous to known)
await analytics.identify('user_123', {
  name: 'John Doe',
  email: 'john@example.com',
  plan: 'premium'
})
```

### Web Vitals Monitoring

Automatically tracks Core Web Vitals with detailed breakdowns:

```typescript
// You can access vitals data through the analytics engine
const sessionId = analytics.getSessionId()
console.log('Session:', sessionId)
```

### Disable Analytics

```tsx
// If you need to disable analytics (GDPR compliance)
<NexusProvider disableAnalytics>
  {children}
</NexusProvider>
```

## 💾 Caching System

### Cache Strategies

```typescript
// 1. Memory Cache (Default - Fastest)
const client = createNexusClient({
  cacheStrategy: 'memory', // In-memory cache, cleared on page refresh
  revalidateTime: 60 // Seconds
})

// 2. LocalStorage Cache (Persistent)
const client = createNexusClient({
  cacheStrategy: 'localStorage', // Persists across sessions
  revalidateTime: 300 // 5 minutes
})

// 3. No Cache (Always Fresh)
const client = createNexusClient({
  cacheStrategy: 'none' // Always fetch from network
})
```

### Cache Invalidation

```typescript
// Invalidate by tags
nexus.content.invalidateCache(['page:home', 'collection:blog_posts'])

// Clear all cache
nexus.content.clearCache()

// Manual cache control
const page = await nexus.getPage('home', {
  forceRefresh: true, // Skip cache
  revalidate: 0 // No revalidation
})

// Get cache statistics
const stats = nexus.content.getCacheStats()
console.log(stats)
/*
{
  memory: {
    size: 15,
    hits: 124,
    misses: 12,
    hitRate: 0.91,
    evictions: 3
  },
  browser: { size: 24567 },
  local: { loaded: true }
}
*/
```

### Cache Tags

Auto-generated tags for smart invalidation:

```typescript
// Content gets tagged automatically:
// - `nexus_project_${projectId}`
// - `content_${slug}`
// - `collection_${collectionId}`
// - `item_${itemId}`
// - `nexus_global_config`

// You can add custom tags:
const page = await nexus.getPage('home', {
  tags: ['homepage', 'featured']
})

// Later, invalidate all homepage content:
nexus.content.invalidateCache(['homepage'])
```

## 🛠️ CLI Tool

### Installation

```bash
# If installed globally
npm install -g @nexushub/client

# Or use npx
npx @nexushub/client <command>
```

### Available Commands

```bash
# Initialize project structure
npx nexus init

# Pull content from NexusHub to local cache
npx nexus pull --api-key YOUR_KEY --project-id YOUR_ID

# Seed content from local files to NexusHub
npx nexus seed --input .nexus/seed

# Trigger deployment
npx nexus deploy --environment production

# Check project status
npx nexus status

# Force overwrite local cache
npx nexus pull --force
```

### Project Structure

```
.nexus/
├── cache.json          # Local cache (gitignored)
├── seed/              # Seed data for content
│   ├── pages.json     # Static pages
│   ├── collections/   # Dynamic collections
│   │   ├── blog_posts.json
│   │   └── products.json
│   └── globals.json   # Global settings
└── README.md
```

### Environment Variables for CLI

```bash
# .env.local (for CLI)
NEXUS_API_KEY=your_api_key_here
NEXUS_PROJECT_ID=your_project_id_here
NEXUS_API_URL=https://api.nexushub.com/v1
```

## 📚 API Reference

### `NexusClient`

#### Constructor

```typescript
new NexusClient(config?: Partial<NexusConfig>)
```

#### Methods

- `getPage<T>(slug: string, options?)`: Get singleton page
- `getConfig()`: Get current config
- `content`: ContentEngine instance
- `analytics`: AnalyticsEngine instance (internal)

### `ContentEngine`

#### Core Methods

```typescript
// Content fetching
getPage<T>(slug: string, options?): Promise<T>
getCollection<T>(collectionId: string, query?, options?): Promise<CollectionResponse<T>>
getItem<T>(collectionId: string, itemId: string, options?): Promise<T>
getGlobals<T>(options?): Promise<T>

// Search
search<T>(query: string, options?): Promise<{ results: T[], total: number }>

// Cache management
invalidateCache(tags: string[]): void
clearCache(): void
getCacheStats(): CacheStats

// Real-time
subscribeToUpdates(callback): () => void
prefetch(urls: string[]): Promise<void>
```

### `useNexusAuth()` Hook

#### Returns

```typescript
{
  user: SiteUser | null,
  isLoading: boolean,
  error: Error | null,
  isAuthenticated: boolean,
  
  // Methods
  login: (credentials: LoginCredentials) => Promise<void>,
  register: (credentials: RegisterCredentials) => Promise<void>,
  logout: () => Promise<void>,
  loginWithGoogle: () => void,
  updateProfile: (data: Partial<SiteUser>) => Promise<void>
}
```

### Types

```typescript
interface NexusConfig {
  projectId: string;
  apiUrl: string;
  apiKey?: string;
  debug?: boolean;
  cacheStrategy?: 'memory' | 'localStorage' | 'none';
  revalidateTime?: number;
  timeout?: number;
  retries?: number;
}

interface ContentResponse<T = any> {
  id: string;
  type: string;
  data: T;
  meta: {
    version: number;
    updatedAt: string;
    locale?: string;
    cacheStatus: 'hit' | 'miss' | 'stale';
  };
}

interface CollectionResponse<T = any> {
  items: T[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
  hasNext: boolean;
  hasPrev: boolean;
  meta?: {
    fetchedAt: string;
    cacheStatus: string;
    filters?: Record<string, any>;
  };
}
```

## 🚦 Examples

### Next.js App Router

```tsx
// app/layout.tsx
import { NexusProvider } from '@nexushub/client'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <NexusProvider>
          {children}
        </NexusProvider>
      </body>
    </html>
  )
}

// app/blog/page.tsx
import { nexus } from '@nexushub/client'

export default async function BlogPage() {
  const posts = await nexus.content.getCollection('blog_posts', {
    page: 1,
    limit: 10,
    sort: 'publishedAt',
    order: 'desc',
    filter: { status: 'published' }
  })
  
  return (
    <div>
      <h1>Blog</h1>
      {posts.items.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </div>
  )
}
```

### Next.js Pages Router

```tsx
// pages/_app.tsx
import { NexusProvider } from '@nexushub/client'

function MyApp({ Component, pageProps }) {
  return (
    <NexusProvider>
      <Component {...pageProps} />
    </NexusProvider>
  )
}

// pages/index.tsx
import { nexus } from '@nexushub/client'

export async function getServerSideProps() {
  const page = await nexus.getPage('home')
  return { props: { page } }
}

export default function Home({ page }) {
  return (
    <div>
      <h1>{page.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: page.content }} />
    </div>
  )
}
```

### React (No Framework)

```tsx
// index.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { NexusProvider } from '@nexushub/client'
import App from './App'

const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(
  <React.StrictMode>
    <NexusProvider projectId="your-project-id">
      <App />
    </NexusProvider>
  </React.StrictMode>
)

// App.tsx
import { nexus, useNexusAuth } from '@nexushub/client'
import { useEffect, useState } from 'react'

function App() {
  const [page, setPage] = useState(null)
  const { user, login } = useNexusAuth()
  
  useEffect(() => {
    nexus.getPage('home').then(setPage)
  }, [])
  
  if (!page) return <div>Loading...</div>
  
  return (
    <div>
      <h1>{page.title}</h1>
      <p>{page.content}</p>
    </div>
  )
}
```

### E-commerce Example

```tsx
// components/ProductList.tsx
import { nexus } from '@nexushub/client'

export async function ProductList({ category }) {
  const products = await nexus.content.getCollection('products', {
    filter: { category },
    sort: 'createdAt',
    order: 'desc',
    include: ['variants', 'reviews']
  })
  
  const handlePurchase = (product) => {
    // Track purchase in analytics
    nexus['analytics'].trackPurchase({
      order_id: `temp_${Date.now()}`,
      total: product.price,
      currency: 'USD',
      items: [{
        id: product.id,
        name: product.name,
        price: product.price,
        quantity: 1
      }]
    })
  }
  
  return (
    <div className="grid grid-cols-4 gap-4">
      {products.items.map(product => (
        <div key={product.id} className="border p-4">
          <img src={product.image} alt={product.name} />
          <h3>{product.name}</h3>
          <p>${product.price}</p>
          <button 
            onClick={() => handlePurchase(product)}
            className="bg-blue-500 text-white px-4 py-2"
          >
            Add to Cart
          </button>
        </div>
      ))}
    </div>
  )
}
```

## 🐛 Troubleshooting

### Common Issues

#### 1. "Missing projectId" Error

```bash
# Check your environment variables
echo $NEXT_PUBLIC_NEXUS_ID

# Ensure .env.local exists
ls -la .env.local

# Restart dev server after changing env vars
npm run dev
```

#### 2. Cache Not Updating

```typescript
// Force refresh
await nexus.getPage('home', { forceRefresh: true })

// Clear all cache
nexus.content.clearCache()

// Check cache stats
console.log(nexus.content.getCacheStats())
```

#### 3. Analytics Not Tracking

```typescript
// Check if analytics is enabled
const client = createNexusClient({ debug: true })

// Verify in console logs
// Should see: "[NexusHub] Analytics started"
```

#### 4. Authentication Issues

```typescript
// Check CORS settings in NexusHub dashboard
// Ensure your domain is whitelisted

// Verify HttpOnly cookies are supported
// Some ad blockers may interfere
```

#### 5. TypeScript Errors

```typescript
// If you get "Property 'content' does not exist"
// Make sure you're using the correct import:
import { nexus } from '@nexushub/client' // Correct
import nexus from '@nexushub/client' // Wrong
```

### Debug Mode

Enable debug logging to see detailed information:

```typescript
const client = createNexusClient({
  debug: true,
  cacheStrategy: 'memory'
})

// Check console for:
// - Cache hits/misses
// - Network requests
// - Performance metrics
// - Analytics events
```

### Performance Monitoring

```typescript
// Get performance metrics
const stats = nexus.content.getCacheStats()
console.log('Cache Hit Rate:', stats.memory.hitRate)

// Monitor Web Vitals in analytics dashboard
// Visit: https://dashboard.nexushub.com/analytics
```

## 🔧 Advanced Configuration

### Custom Cache Implementation

```typescript
import { MemoryCache, BrowserCache } from '@nexushub/client'

// Extend existing cache
class CustomMemoryCache extends MemoryCache {
  constructor(options) {
    super({ ...options, maxSize: 2000 })
  }
  
  set(key, data, options) {
    // Add custom logic
    console.log(`Caching: ${key}`)
    super.set(key, data, options)
  }
}

// Use in your app
const customCache = new CustomMemoryCache({ ttl: 60000 })
```

### Middleware & Interceptors

```typescript
// Request/Response interceptors
const client = createNexusClient({
  interceptors: {
    request: (config) => {
      // Add custom headers
      config.headers['X-Custom-Header'] = 'value'
      return config
    },
    response: (response) => {
      // Transform response
      return response.data
    },
    error: (error) => {
      // Custom error handling
      console.error('Request failed:', error)
      throw error
    }
  }
})
```

### Multiple Projects

```typescript
import { createNexusClient } from '@nexushub/client'

const mainClient = createNexusClient({
  projectId: 'main-project',
  apiKey: 'main-key'
})

const secondaryClient = createNexusClient({
  projectId: 'secondary-project',
  apiKey: 'secondary-key',
  apiUrl: 'https://api-2.nexushub.com/v1'
})

// Use both clients in your app
const [mainPage, secondaryPage] = await Promise.all([
  mainClient.getPage('home'),
  secondaryClient.getPage('home')
])
```

## 📈 Performance Benchmarks

```
Cache Performance:
├── Memory Cache: 0.1ms - 1ms
├── LocalStorage: 1ms - 5ms
└── Network: 50ms - 300ms

Bundle Size:
├── Core SDK: 15kb gzipped
├── With Analytics: 28kb gzipped
└── Full Package: 35kb gzipped

Memory Usage:
├── Memory Cache: ~5MB max
├── LocalStorage: ~5MB max
└── Browser Memory: ~10MB typical
```

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository**
2. **Clone your fork**

```bash
git clone https://github.com/your-username/nexushub-client-sdk.git
cd nexushub-client-sdk/packages/client-sdk
```

1. **Install dependencies**

```bash
npm install
```

1. **Run tests**

```bash
npm test
npm run test:coverage
```

1. **Make changes and test**

```bash
npm run dev  # Watch mode
npm run build
```

1. **Submit a Pull Request**

### Development Scripts

```bash
# Build
npm run build

# Development (watch mode)
npm run dev

# Type checking
npm run type-check

# Linting
npm run lint

# Testing
npm test                 # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report
npm run test:debug      # Verbose output
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Links

- [NexusHub Dashboard](https://dashboard.nexushub.com)
- [Documentation](https://docs.nexushub.com)
- [API Reference](https://docs.nexushub.com/api)
- [GitHub Issues](https://github.com/nexushub/client-sdk/issues)
- [Discord Community](https://discord.gg/nexushub)

## 🏆 Support

- **Community Support**: [GitHub Discussions](https://github.com/nexushub/client-sdk/discussions)
- **Priority Support**: Available for enterprise plans
- **Bug Reports**: [GitHub Issues](https://github.com/nexushub/client-sdk/issues)
- **Feature Requests**: Submit via GitHub Issues

---

<div align="center">
Made with ❤️ by the NexusHub Team
<br/>
<a href="https://nexushub.com">nexushub.com</a>
</div>