npm package: @rivtor/admin
Description: Production-ready super admin panel for B2B SaaS founders
Author: Rivtor
Latest version: 1.1.0

# @rivtor/admin

[![npm version](https://badge.fury.io/js/%40rivtor%2Fadmin.svg)](https://www.npmjs.com/package/@rivtor/admin)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Production-ready super admin panel for B2B SaaS founders.

## Overview

`@rivtor/admin` is the "God Mode" module that every founder needs. Automatically inject a `/admin` route into your app with user impersonation, organization management, and error monitoring—without writing a single line of admin UI code.

**Key Features:**
- 🎭 **User Impersonation** - Login as any user for support
- 👥 **User Management** - View and manage all users
- 🏢 **Organization View** - See all teams and members
- 💳 **Manual Upgrades** - Comp users or upgrade plans
- 📊 **Error Logs** - View application error logs
- 🔒 **Secure** - Admin-only middleware protection

## Installation

```bash
npm install @rivtor/admin
```

## Quick Start

### Middleware Setup

```typescript
// middleware.ts
import { createAdminMiddleware } from '@rivtor/admin';

export const middleware = createAdminMiddleware({
  // Only allow specific admin emails
  adminEmails: ['founder@yourapp.com', 'admin@yourapp.com'],
});

export const config = {
  matcher: ['/admin/:path*'],
};
```

### Admin Page

```tsx
// app/admin/page.tsx
import { RivtorAdminPanel } from '@rivtor/admin/react';

export default function AdminPage() {
  return <RivtorAdminPanel />;
}
```

**That's it!** You now have a full admin panel at `/admin`.

## API Reference

### Server Methods

- `impersonateUser(adminId, targetUserId)` - Login as any user
- `getAllOrganizations()` - View all organizations
- `upgradeUserPlan(userId, plan)` - Manually upgrade user
- `getErrorLogs(filters)` - Fetch error logs
- `isAdmin(userId)` - Check if user is admin

### React Components

- `<RivtorAdminPanel />` - Complete admin dashboard
- `<RivtorUserList />` - User list with search and impersonation
- `<RivtorOrganizationTable />` - Organization management table

## Features

### User Impersonation

```typescript
import { admin } from '@rivtor/admin';

// Server action
export async function impersonateUser(targetUserId: string) {
  const currentUser = await auth.requireUser();
  await admin.isAdmin(currentUser.id);
  
  // Generate impersonation token
  const token = await admin.impersonateUser(currentUser.id, targetUserId);
  
  // User is now logged in as targetUserId
  return { token };
}
```

### Manual Plan Upgrade

```typescript
// Comp a user to Pro plan
await admin.upgradeUserPlan('user_123', 'pro');
```

### View All Organizations

```typescript
const orgs = await admin.getAllOrganizations();
// Returns: [{ id, name, owner, memberCount, plan }]
```

## Environment Variables

```bash
# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Admin Configuration
ADMIN_EMAILS=founder@app.com,admin@app.com

# Stripe (For plan management)
STRIPE_SECRET_KEY=sk_...
```

## Security

⚠️ **CRITICAL**: Only expose `/admin` routes to verified admin users.

The middleware automatically checks:
1. User is authenticated
2. User email is in `ADMIN_EMAILS` env variable
3. User has admin role in database (if using RBAC)

## Admin UI Preview

The `<RivtorAdminPanel />` includes:
- User search and filtering
- Organization browser
- Impersonation button (login as user)
- Plan upgrade controls
- Error log viewer
- Activity timeline

## License

MIT © Rivtor

## Support

- Email: legal@rivtor.com
- Documentation: [GitHub Wiki](https://github.com/rivtor/rivtor-admin/wiki)

---

**Built with care by [Rivtor](https://rivtor.com)**