npm package: @rivtor/sdk
Description: The Operating System for SaaS - Unified Rivtor SDK
Author: Rivtor
Latest version: 1.1.0

# @rivtor/sdk

> The Operating System for SaaS

The unified Rivtor SDK that consolidates all core modules into a single package for maximum developer productivity.

## Installation

```bash
npm install @rivtor/sdk
```

## Environment Variables

```env
NEXT_PUBLIC_VOCO_URL=https://your-app.rivtor.com
VOCO_API_KEY=voco_sk_...
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
NEXT_PUBLIC_STRIPE_KEY=pk_live_...
```

## Quick Start

### 1. Wrap Your App

```tsx
// app/layout.tsx
import { VocoProvider } from '@rivtor/sdk/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <VocoProvider>{children}</VocoProvider>
      </body>
    </html>
  );
}
```

### 2. Add Middleware

```ts
// middleware.ts
import { vocoMiddleware } from '@rivtor/sdk/middleware';

export default vocoMiddleware;

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

### 3. Use the SDK

```tsx
import { useVocoAuth, useVocoTenant, VocoGate } from '@rivtor/sdk/react';
import { voco } from '@rivtor/sdk/server';

// Client-side
function Dashboard() {
  const { user, logout } = useVocoAuth();
  const { currentOrg } = useVocoTenant();

  return (
    <VocoGate feature="analytics">
      <AnalyticsDashboard />
    </VocoGate>
  );
}

// Server-side (with automatic tenant isolation)
async function getData() {
  const data = await voco.db.from('projects').select('*');
  return data; // Automatically filtered by tenant_id
}
```

## Included Modules

### Core Modules
| Module | Purpose |
|--------|---------|
| `@rivtor/kernel` | Auth, Billing, Legal, Compliance |
| `@rivtor/tenant` | Multi-tenancy & RBAC |
| `@rivtor/features` | Feature gating & Entitlements |
| `@rivtor/meter` | Usage tracking & Limits |
| `@rivtor/notify` | Notifications (email, in-app, push) |
| `@rivtor/admin` | Super admin panel |

### Security & Compliance
| Module | Purpose |
|--------|---------|
| `@rivtor/a11y-guard` | WCAG 2.1 AA accessibility with ESLint plugin |
| `@rivtor/erasure` | GDPR Right to be Forgotten with retention engine |
| `@rivtor/portability` | GDPR Data Portability with schema discovery |
| `@rivtor/residency` | Schrems II data sovereignty with Cloudflare Workers |
| `@rivtor/consent` | GDPR cookie consent with GeoIP detection |
| `@rivtor/invoice` | EU VAT invoice generator with PDF rendering |

### Developer Experience
| Module | Purpose |
|--------|---------|
| `@rivtor/codegen` | TypeScript schema generator with watch mode |
| `@rivtor/local` | Offline development with SQLite adapter |
| `@rivtor/errors` | Error dictionary with i18n support |

### Growth
| Module | Purpose |
|--------|---------|
| `@rivtor/viral` | Referral system with fraud detection |

## Components

### Identity
- `<VocoSignIn />` - Complete login card
- `<VocoUserButton />` - Avatar dropdown

### Tenant
- `<VocoOrgSwitcher />` - Team switcher
- `<VocoInviteForm />` - Member invite form

### Billing
- `<VocoPricingTable />` - Stripe pricing columns
- `<VocoBillingPortalButton />` - Stripe portal button

### Compliance
- `<VocoFooterLinks />` - Privacy, Terms, DPA links
- `<VocoGate />` - Feature gate wrapper

## Hooks

```tsx
useVocoAuth()    // { user, login, logout, isLoading }
useVocoTenant()  // { currentOrg, switchOrg, members }
useVocoGate(f)   // { isEnabled, upgradeUrl }
useVocoNotify()  // { notifications, markRead }
```

## Server API

```ts
import { voco } from '@rivtor/sdk/server';

// Safe database (auto tenant isolation)
await voco.db.from('table').select('*');

// Auth
await voco.auth.requireUser(request);

// Features
await voco.features.requireFeature(userId, 'analytics');

// Meter
await voco.meter.checkLimit(userId, 'api_calls');
```

## License

MIT © Rivtor