spaps-sdk 1.0.2 → 1.1.1

package/README.md

@@ -1,700 +1,311 @@
-# Sweet Potato SDK
+# @spaps/sdk
 
-[![npm version](https://badge.fury.io/js/spaps-sdk.svg)](https://www.npmjs.com/package/spaps-sdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-4.5%2B-blue)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+> Sweet Potato Authentication & Payment Service SDK
 
-A comprehensive TypeScript SDK for integrating with the Sweet Potato Authentication and Payment Service (SPAPS). This SDK provides complete functionality for user authentication, Stripe payment processing, subscription management, and more.
+Zero-config client for SPAPS authentication, payments, and permission checking. Works automatically with local development mode.
 
-**[📚 Full API Documentation](../API_INTEGRATION_GUIDE.md) | [🛠️ Stripe Admin Guide](../STRIPE_ADMIN_GUIDE.md)**
+## 🔐 New in v1.1.0: Admin API Methods!
 
-## Features
-
-### Authentication
-- 🔐 **Multi-wallet Authentication**: Support for Solana, Ethereum, Bitcoin, and Base wallets
-- 🔑 **Traditional Authentication**: Email/password and magic link authentication
-- 🔄 **Token Management**: Automatic token refresh and secure storage utilities
-- 🧰 **Wallet Utilities**: Address validation, chain detection
-
-### Payments & Subscriptions
-- 💳 **Stripe Checkout Sessions**: One-time payments and subscriptions
-- 📦 **Product Management**: List, create, update products and prices
-- 🔄 **Subscription Management**: Create, update, cancel subscriptions
-- 🏪 **Customer Portal**: Self-service billing management
-- 🎣 **Webhook Handling**: Secure event processing
-
-### Developer Experience
-- 🎯 **TypeScript First**: Full TypeScript support with comprehensive type definitions
-- 🛡️ **Error Handling**: Robust error handling with custom error types
-- 🔁 **Retry Logic**: Built-in retry mechanism with exponential backoff
-- ⚛️ **React Integration**: Ready-to-use hooks and components
-- 📚 **Extensive Examples**: Real-world usage patterns
-- 🧪 **Well Tested**: Comprehensive test suite with high coverage
-
-## Installation
-
-```bash
-npm install spaps-sdk
-# or
-yarn add spaps-sdk
-# or  
-pnpm add spaps-sdk
-```
-
-> **📍 Important:** SPAPS runs on port **3456**. This is standardized across all tools.
-
-### Requirements
-
-- Node.js 14+ or modern browser
-- TypeScript 4.5+ (optional, for TypeScript projects)
-
-## Quick Start
-
-### Basic Setup
-
-```typescript
-import { SweetPotatoSDK, TokenManager } from 'spaps-sdk';
-
-// Initialize the SDK
-const sdk = new SweetPotatoSDK({
-  apiUrl: 'http://localhost:3456',  // Always port 3456 for local dev
-  // apiUrl: 'https://api.sweetpotato.dev',  // Production (not available yet)
-  apiKey: process.env.SPAPS_API_KEY || 'test_key_local_dev_only',
-  timeout: 30000,  // Optional: 30 second timeout
-  retries: 3       // Optional: 3 retry attempts
-});
-
-// Auto-restore authentication state (browser only)
-await TokenManager.autoRefreshToken(sdk);
-```
-
-## Authentication Examples
-
-### Wallet Authentication (Complete Flow)
+Built-in admin API methods for Stripe product management:
 
 ```typescript
-// Complete implementation with proper signature handling
-const walletAddress = '0x742d35CC6354C7Cb24b5d2C2C7f9Ff5Ef8B4d5f6';
-
-const authResponse = await sdk.auth.authenticateWallet(
-  walletAddress,
-  async (message) => {
-    // The SDK provides the message to sign
-    // You must return the signed message
-    
-    // Browser (MetaMask):
-    if (typeof window !== 'undefined' && window.ethereum) {
-      return await window.ethereum.request({
-        method: 'personal_sign',
-        params: [message, walletAddress]
-      });
-    }
-    
-    // Node.js (ethers.js):
-    // const { Wallet } = require('ethers');
-    // const wallet = new Wallet(privateKey);
-    // return await wallet.signMessage(message);
-  },
-  'ethereum',      // Chain type: 'ethereum', 'solana', 'bitcoin', 'base'
-  'username123'    // Optional: username for new users
-);
-
-// Store tokens for future use
-TokenManager.storeTokens(authResponse);
-console.log('User:', authResponse.user);
-```
+import { SPAPSClient } from 'spaps-sdk';
 
-### Email/Password Authentication
-
-```typescript
-const authResponse = await sdk.auth.signInWithPassword({
-  email: 'user@example.com',
-  password: 'securePassword123!'
+const spaps = new SPAPSClient({
+  apiKey: 'your-api-key',
+  apiUrl: 'https://api.sweetpotato.dev'
 });
 
-TokenManager.storeTokens(authResponse);
-```
+// Authenticate as admin
+await spaps.signIn('admin@example.com', 'password');
 
-### Magic Link Authentication
-
-```typescript
-await sdk.auth.requestMagicLink({
-  email: 'user@example.com',
-  redirect_url: 'https://myapp.com/auth/callback'
+// Admin API methods
+await spaps.admin.createProduct({
+  name: 'Premium Plan',
+  category: 'subscription',
+  description: 'Advanced features'
 });
-// User will receive email with authentication link
-```
-
-## Payment Examples
 
-### One-Time Payment
-
-```typescript
-// Using existing price
-const checkoutSession = await sdk.payments.createPaymentCheckout({
-  price_id: 'price_1234567890',
-  success_url: 'https://myapp.com/success',
-  cancel_url: 'https://myapp.com/cancel',
-  metadata: {
-    order_id: 'order_123',
-    user_type: 'premium'
-  }
+await spaps.admin.updateProduct('prod_123', {
+  name: 'Premium Plan Pro'
 });
 
-// Redirect to Stripe Checkout
-window.location.href = checkoutSession.url!;
-```
-
-### Dynamic Pricing
-
-```typescript
-// Create payment with custom price
-const checkoutSession = await sdk.payments.createPaymentCheckout({
-  product_name: 'Premium Feature Access',
-  amount: 2999, // $29.99 in cents
+await spaps.admin.createPrice({
+  product_id: 'prod_123',
+  unit_amount: 2999,
   currency: 'usd',
-  quantity: 1,
-  success_url: 'https://myapp.com/success',
-  cancel_url: 'https://myapp.com/cancel'
+  interval: 'month'
 });
-```
-
-### Subscription Creation
 
-```typescript
-const subscriptionCheckout = await sdk.payments.createSubscriptionCheckout({
-  price_id: 'price_monthly_subscription',
-  success_url: 'https://myapp.com/subscription-success',
-  cancel_url: 'https://myapp.com/subscription-cancel',
-  trial_period_days: 14,
-  metadata: {
-    subscription_type: 'pro',
-    source: 'website'
-  }
-});
+// Super admin operations
+await spaps.admin.syncProducts();
 ```
 
-### Product Management
-
-```typescript
-// List all products
-const products = await sdk.payments.listProducts({
-  category: 'subscription',
-  active: true,
-  limit: 20
-});
-
-// Get specific product with prices
-const product = await sdk.payments.getProduct('prod_123');
-
-// Create new product (admin only)
-const newProduct = await sdk.payments.createProduct({
-  name: 'New Premium Plan',
-  description: 'Enhanced features for power users',
-  category: 'subscription',
-  metadata: {
-    tier: 'premium',
-    features: 'advanced-analytics,priority-support'
-  }
-});
-```
+## 🔐 Permission Utilities
 
-### Subscription Management
+Built-in permission checking and role-based access control:
 
 ```typescript
-// List user subscriptions
-const subscriptions = await sdk.payments.listSubscriptions({
-  status: 'active'
-});
+import { isAdminAccount, canAccessAdmin, getUserRole } from 'spaps-sdk';
 
-// Update subscription
-await sdk.payments.updateSubscription('sub_123', {
-  price_id: 'price_new_plan',
-  metadata: { upgrade_reason: 'user_requested' }
-});
-
-// Cancel subscription at period end
-await sdk.payments.updateSubscription('sub_123', {
-  cancel_at_period_end: true
-});
+// Check admin status
+const isAdmin = isAdminAccount('buildooor@gmail.com'); // true
 
-// Create customer portal session
-const portalSession = await sdk.payments.createCustomerPortalSession({
-  return_url: 'https://myapp.com/account'
-});
-window.location.href = portalSession.url;
-```
-
-## Token Management
-
-### Automatic Token Refresh
-
-```typescript
-// Set up automatic token refresh
-async function setupAutoRefresh() {
-  const refreshSuccess = await TokenManager.autoRefreshToken(sdk);
-  
-  if (refreshSuccess) {
-    console.log('Authentication restored from stored tokens');
-  } else {
-    console.log('No valid tokens found, user needs to authenticate');
-  }
+// Check admin access with detailed result
+const adminCheck = canAccessAdmin(user);
+if (adminCheck.allowed) {
+  // Show admin UI
 }
 
-// Manual token refresh
-async function refreshTokens() {
-  try {
-    const refreshToken = TokenManager.getRefreshToken();
-    if (refreshToken) {
-      const newTokens = await sdk.auth.refreshToken(refreshToken);
-      TokenManager.storeTokens(newTokens);
-    }
-  } catch (error) {
-    console.error('Token refresh failed:', error);
-    // Redirect to login
-  }
-}
-```
-
-### Logout
+// Get user role
+const role = getUserRole('user@example.com'); // 'user' | 'admin' | 'guest'
 
-```typescript
-async function logout() {
-  try {
-    await sdk.auth.logout();
-    TokenManager.clearTokens();
-    console.log('Successfully logged out');
-  } catch (error) {
-    console.error('Logout failed:', error);
-  }
+// Check if authenticated user is admin
+if (spaps.isAdmin(currentUser)) {
+  // Show admin features
 }
 ```
 
-## User Management
-
-### Get Current User
+See [PERMISSIONS.md](./PERMISSIONS.md) for React examples and complete documentation.
 
-```typescript
-async function getCurrentUser() {
-  try {
-    const user = await sdk.auth.getCurrentUser();
-    console.log('Current user:', user);
-    return user;
-  } catch (error) {
-    console.error('Failed to get user:', error);
-    // User might not be authenticated
-  }
-}
-```
-
-### Check Authentication Status
+## Installation
 
-```typescript
-function checkAuthStatus() {
-  if (sdk.auth.isAuthenticated()) {
-    console.log('User is authenticated');
-  } else {
-    console.log('User needs to log in');
-  }
-}
+```bash
+npm install spaps-sdk
+# or
+yarn add spaps-sdk
+# or
+pnpm add spaps-sdk
 ```
 
-## Utility Functions
+### Compatibility
 
-### Wallet Address Validation
+- ✅ **Node.js**: Fully supported (v14+) with automatic fetch polyfill
+- ✅ **Browser**: Works in all modern browsers  
+- ✅ **TypeScript**: Full type definitions included
+- ✅ **Next.js**: Server and client components supported
+- ✅ **React Native**: Compatible with proper setup
 
-```typescript
-import { WalletUtils } from '@sweet-potato/auth-sdk';
+The SDK automatically includes a `cross-fetch` polyfill for Node.js environments that don't have native fetch support.
 
-// Detect chain type
-const chainType = WalletUtils.detectChainType('0x742d35Cc6634C0532925a3b8D6Ac6d8F49c3589F');
-console.log(chainType); // 'ethereum'
+## Quick Start
 
-// Validate address format
-const isValid = WalletUtils.isValidAddress('0x742d35Cc6634C0532925a3b8D6Ac6d8F49c3589F', 'ethereum');
-console.log(isValid); // true
+```javascript
+import { SPAPSClient } from 'spaps-sdk';
+// or
+const { SPAPSClient } = require('spaps-sdk');
 
-// Auto-detect and validate
-const isValidAuto = WalletUtils.isValidAddress('0x742d35Cc6634C0532925a3b8D6Ac6d8F49c3589F');
-console.log(isValidAuto); // true
-```
+// Auto-detects local mode - no API key needed for localhost!
+const spaps = new SPAPSClient({
+  apiUrl: 'http://localhost:3300' // Optional, auto-detected
+});
 
-### Token Utilities
+// Login
+const { data } = await spaps.login('user@example.com', 'password');
+console.log('User:', data.user);
 
-```typescript
-// Check if token is expired
-const token = TokenManager.getAccessToken();
-if (token && TokenManager.isTokenExpired(token)) {
-  console.log('Token is expired, refreshing...');
-  await refreshTokens();
+// Check authentication
+if (spaps.isAuthenticated()) {
+  const user = await spaps.getUser();
+  console.log('Current user:', user.data);
 }
 ```
 
-## Error Handling
+## Features
 
-```typescript
-import { SweetPotatoAPIError } from '@sweet-potato/auth-sdk';
+### 🚀 Zero Configuration
+- **Auto-detects local mode** - No API key needed for localhost
+- **Auto-refreshes tokens** - Handles expired tokens automatically
+- **TypeScript support** - Full type definitions included
 
-try {
-  await sdk.auth.signInWithPassword({
-    email: 'invalid@example.com',
-    password: 'wrongpassword'
-  });
-} catch (error) {
-  if (error instanceof SweetPotatoAPIError) {
-    console.error('API Error:', {
-      message: error.message,
-      code: error.code,
-      status: error.status,
-      details: error.details
-    });
-    
-    // Handle specific error codes
-    switch (error.code) {
-      case 'INVALID_CREDENTIALS':
-        console.log('Please check your email and password');
-        break;
-      case 'RATE_LIMITED':
-        console.log('Too many attempts, please wait');
-        break;
-      default:
-        console.log('An unexpected error occurred');
-    }
-  }
-}
-```
+### 🔐 Authentication Methods
+```javascript
+// Email/Password
+await spaps.login(email, password);
+await spaps.register(email, password);
 
-## Advanced Usage
+// Wallet Authentication
+await spaps.walletSignIn(walletAddress, signature, message, 'solana');
 
-### Custom Requests
+// Token Management
+await spaps.refresh();
+await spaps.logout();
 
-```typescript
-// Make custom authenticated requests
-async function makeCustomRequest() {
-  try {
-    const response = await sdk.request(
-      'GET',
-      '/api/custom-endpoint',
-      null,
-      true // requires authentication
-    );
-    
-    console.log('Custom response:', response.data);
-  } catch (error) {
-    console.error('Custom request failed:', error);
-  }
-}
+// Get User
+const user = await spaps.getUser();
 ```
 
-### Health Check
+### 💳 Stripe Integration
+```javascript
+// Create checkout session
+const session = await spaps.createCheckoutSession(priceId, successUrl);
+window.location.href = session.data.url;
 
-```typescript
-async function checkAPIHealth() {
-  const isHealthy = await sdk.healthCheck();
-  if (isHealthy) {
-    console.log('API is healthy');
-  } else {
-    console.log('API is down or unreachable');
-  }
-}
+// Manage subscription
+const subscription = await spaps.getSubscription();
+await spaps.cancelSubscription();
 ```
 
-## React Integration Example
+### 📊 Usage Tracking
+```javascript
+// Check balance
+const balance = await spaps.getUsageBalance();
+console.log(`Credits: ${balance.data.balance}`);
 
-```typescript
-import React, { useEffect, useState } from 'react';
-import { createSweetPotatoSDK, TokenManager, User } from '@sweet-potato/auth-sdk';
-
-const sdk = createSweetPotatoSDK({
-  apiUrl: process.env.REACT_APP_API_URL!,
-  apiKey: process.env.REACT_APP_API_KEY!
-});
-
-export function useAuth() {
-  const [user, setUser] = useState<User | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    async function restoreAuth() {
-      try {
-        const restored = await TokenManager.autoRefreshToken(sdk);
-        if (restored) {
-          const currentUser = await sdk.auth.getCurrentUser();
-          setUser(currentUser);
-        }
-      } catch (error) {
-        console.error('Failed to restore authentication:', error);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    restoreAuth();
-  }, []);
-
-  const login = async (email: string, password: string) => {
-    const result = await sdk.auth.signInWithPassword({ email, password });
-    TokenManager.storeTokens(result);
-    setUser(result.user);
-    return result;
-  };
-
-  const logout = async () => {
-    await sdk.auth.logout();
-    TokenManager.clearTokens();
-    setUser(null);
-  };
-
-  return {
-    user,
-    loading,
-    login,
-    logout,
-    isAuthenticated: !!user
-  };
-}
+// Record usage
+await spaps.recordUsage('api-call', 1);
 ```
 
-## Configuration Options
+## Configuration
 
-```typescript
-interface SweetPotatoConfig {
-  apiUrl: string;          // Required: Your API base URL
-  apiKey: string;          // Required: Your application API key
-  timeout?: number;        // Optional: Request timeout in ms (default: 30000)
-  retries?: number;        // Optional: Number of retries (default: 3)
-}
+### Production Mode
+```javascript
+const spaps = new SPAPSClient({
+  apiUrl: 'https://api.sweetpotato.dev',
+  apiKey: 'spaps_your_api_key_here',
+  timeout: 10000 // Optional timeout in ms
+});
 ```
 
-## TypeScript Types
-
-The SDK exports comprehensive TypeScript types for all API responses and request payloads:
-
-```typescript
-import type {
-  User,
-  UserWallet,
-  AuthResponse,
-  NonceResponse,
-  WalletSignInRequest,
-  TraditionalLoginRequest,
-  ApiResponse,
-  SweetPotatoAPIError
-} from '@sweet-potato/auth-sdk';
+### Local Development Mode (Auto-detected)
+```javascript
+const spaps = new SPAPSClient();
+// Automatically uses http://localhost:3300 with no API key
 ```
 
-## Browser Compatibility
-
-The SDK supports all modern browsers with ES2018+ support. For older browsers, you may need to include polyfills for:
-
-- `fetch` API
-- `Promise`
-- `async/await`
-
-## Error Codes
-
-Common error codes you might encounter:
-
-- `INVALID_CREDENTIALS`: Invalid email/password or wallet signature
-- `MISSING_REQUIRED_FIELDS`: Required fields are missing from request
-- `INVALID_SIGNATURE`: Wallet signature verification failed
-- `RATE_LIMITED`: Too many requests, rate limit exceeded
-- `UNAUTHORIZED`: Invalid or expired tokens
-- `INVALID_APPLICATION`: Invalid API key or application configuration
-- `INTERNAL_SERVER_ERROR`: Server-side error occurred
-
-## API Reference
-
-### SDK Classes
-
-#### `SweetPotatoSDK`
-Main SDK class that provides access to all services.
-
-#### `AuthService`
-- `authenticateWallet()` - Complete wallet authentication flow
-- `signInWithPassword()` - Email/password login
-- `signUp()` - Create new account
-- `requestMagicLink()` - Send magic link email
-- `verifyMagicLink()` - Verify magic link token
-- `refreshToken()` - Refresh access token
-- `logout()` - Sign out and invalidate tokens
-- `getCurrentUser()` - Get authenticated user
-- `isAuthenticated()` - Check auth status
-
-#### `PaymentsService`
-- `createCheckoutSession()` - Create Stripe checkout
-- `createPaymentCheckout()` - Simplified one-time payment
-- `createSubscriptionCheckout()` - Simplified subscription
-- `listProducts()` - Get available products
-- `getProduct()` - Get product details
-- `createProduct()` - Create product (admin)
-- `updateProduct()` - Update product (admin)
-- `syncProducts()` - Sync from Stripe (admin)
-- `listSubscriptions()` - User's subscriptions
-- `updateSubscription()` - Modify subscription
-- `cancelSubscription()` - Cancel subscription
-- `createCustomerPortalSession()` - Billing portal
-
-#### `TokenManager`
-Static utility class for browser token management.
-- `storeTokens()` - Save tokens to localStorage
-- `getAccessToken()` - Retrieve access token
-- `getRefreshToken()` - Retrieve refresh token
-- `clearTokens()` - Remove all tokens
-- `isTokenExpired()` - Check token expiration
-- `autoRefreshToken()` - Auto-refresh if needed
-
-#### `WalletUtils`
-Static utility class for wallet operations.
-- `detectChainType()` - Identify blockchain from address
-- `isValidAddress()` - Validate wallet address format
-
-## What's NOT in the SDK
-
-> **⚠️ Important:** These features require direct API calls with admin authentication.
-
-### Whitelist Management  
-❌ **Not available:** `sdk.whitelist.check()`, `sdk.admin.addToWhitelist()`
-
-Whitelist operations require admin JWT authentication and must be done via direct API calls:
-
-```typescript
-// Authenticate as admin first
-const adminAuth = await sdk.auth.signInWithPassword({
-  email: 'admin@example.com',
-  password: 'admin_password'
-});
+### Environment Variables
+```bash
+# .env
+SPAPS_API_URL=https://api.sweetpotato.dev
+SPAPS_API_KEY=spaps_your_api_key_here
 
-// Use JWT for admin API calls
-const response = await fetch(`${apiUrl}/api/v1/whitelist`, {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${adminAuth.access_token}`,
-    'X-API-Key': apiKey,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    email: 'vip@example.com',
-    tier: 'premium',
-    bypass_payment: true
-  })
-});
+# Next.js
+NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.dev
 ```
 
-### Admin Operations
-❌ **Not available:** `sdk.admin.*` methods
+## Helper Methods
 
-Admin operations require JWT authentication:
-- Application management (create/rotate API keys)
-- User management (admin dashboard)  
-- Direct database operations
-- Product sync from Stripe
+```javascript
+// Check if authenticated
+spaps.isAuthenticated() // boolean
 
-All admin operations follow this pattern:
-1. Authenticate as admin user via `sdk.auth.signInWithPassword()`
-2. Use the JWT token for direct API calls
-3. Include both JWT and API key in headers
+// Get current access token
+spaps.getAccessToken() // string | undefined
 
-See [Stripe Admin Guide](../STRIPE_ADMIN_GUIDE.md) for product management instructions.
+// Set access token manually
+spaps.setAccessToken(token)
 
-## Local Development Mode
+// Check if in local mode
+spaps.isLocalMode() // boolean
 
-When using `npx spaps local`:
-- ✅ Auto-authentication enabled (no signup needed)
-- ✅ Test users pre-created: 'user', 'admin', 'premium'
-- ✅ CORS enabled for all origins
-- ✅ No real API keys required
-- ✅ Mock Stripe integration ready
-- ✅ Runs on port **3456** by default
+// Health check
+await spaps.health()
+```
 
-```bash
-# Start local server
-npx spaps local
+## Import Styles
 
-# Your app can now connect to:
-http://localhost:3456
-```
+All these work:
+```javascript
+// ES6 Import
+import { SPAPSClient } from 'spaps-sdk';
+import SPAPSClient from 'spaps-sdk';
 
-## Production Notes
+// CommonJS
+const { SPAPSClient } = require('spaps-sdk');
+const SPAPSClient = require('spaps-sdk');
 
-⚠️ **Production API is not yet available.** Currently, only local development mode is supported.
+// Alternative names
+import { SPAPS } from 'spaps-sdk';
+import { SweetPotatoSDK } from 'spaps-sdk';
+```
 
-Future production URL: `https://api.sweetpotato.dev` (coming soon)
+## Admin API Methods
 
-## Troubleshooting
+The SDK includes comprehensive admin methods for Stripe product management:
 
-### Common Issues
+### Product Management
 
-**Wrong Port**
 ```typescript
-// ❌ Wrong
-apiUrl: 'http://localhost:3000'
-apiUrl: 'http://localhost:3300'
+// Create product (Admin required)
+const product = await spaps.admin.createProduct({
+  name: 'Premium Plan',
+  category: 'subscription',
+  description: 'Advanced features for power users',
+  images: ['https://example.com/product-image.jpg'],
+  metadata: { feature_set: 'premium' },
+  active: true
+});
 
-// ✅ Correct - always use 3456
-apiUrl: 'http://localhost:3456'
-```
+// Update product (Admin required)
+const updatedProduct = await spaps.admin.updateProduct('prod_123', {
+  name: 'Premium Plan Pro',
+  description: 'Updated features'
+});
 
-**CORS Errors**
-```typescript
-// In local mode, CORS is enabled for all origins
-// In production, ensure your domain is whitelisted
-```
+// Archive product (Admin required)
+await spaps.admin.deleteProduct('prod_123');
 
-**Token Expired**
-```typescript
-// Use TokenManager for automatic refresh
-await TokenManager.autoRefreshToken(sdk);
+// Get products (includes admin metadata if user is admin)
+const { data } = await spaps.admin.getProducts();
+if (data.adminMetadata) {
+  console.log('Total revenue:', data.adminMetadata.total_revenue);
+}
 ```
 
-**Rate Limiting**
+### Price Management
+
 ```typescript
-// SDK automatically retries with exponential backoff
-// Configure retries in SDK initialization
-const sdk = new SweetPotatoSDK({
-  apiUrl: '...',
-  apiKey: '...',
-  retries: 5 // Increase retry count
+// Create price (Admin required)
+const price = await spaps.admin.createPrice({
+  product_id: 'prod_123',
+  unit_amount: 2999, // $29.99
+  currency: 'usd',
+  interval: 'month',
+  interval_count: 1,
+  nickname: 'Monthly Premium'
 });
 ```
 
-## Migration Guide
-
-### From v0.x to v1.0
+### Super Admin Operations
 
 ```typescript
-// Old (v0.x)
-const sdk = new SweetPotatoSDK(apiUrl, apiKey);
-
-// New (v1.0)
-const sdk = new SweetPotatoSDK({
-  apiUrl,
-  apiKey,
-  timeout: 30000,
-  retries: 3
-});
+// Sync all products from Stripe (Super Admin required)
+const syncResult = await spaps.admin.syncProducts();
+console.log(`Synced ${syncResult.data.synced_count} products`);
 ```
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-## Security
+### Permission Checking
 
-- **Never expose API keys in client-side code**
-- **Use environment variables for sensitive data**
-- **Enable HTTPS in production**
-- **Implement proper CORS policies**
-
-Report security vulnerabilities to security@sweetpotato.dev
+```typescript
+// Check if current user can access admin features
+const user = await spaps.getCurrentUser();
+if (spaps.isAdmin(user)) {
+  // Show admin UI components
+  console.log('User has admin privileges');
+} else {
+  // Show regular user UI
+  console.log('Regular user');
+}
+```
 
-## Support
+## Error Handling
 
-- 📖 [Full Documentation](../API_INTEGRATION_GUIDE.md)
-- 💬 Discord: [discord.gg/sweetpotato](https://discord.gg/sweetpotato)
-- 📧 Email: support@sweetpotato.dev
-- 🐛 Issues: [GitHub Issues](https://github.com/sweet-potato/sdk/issues)
+```javascript
+try {
+  await spaps.admin.createProduct(productData);
+} catch (error) {
+  if (error.response?.status === 401) {
+    console.error('Authentication required');
+  } else if (error.response?.status === 403) {
+    console.error('Admin privileges required');
+  } else if (error.response?.status === 429) {
+    console.error('Rate limited');
+  } else {
+    console.error('Error:', error.message);
+  }
+}
+```
 
 ## License
 
-MIT © Sweet Potato Team
+MIT