spaps-sdk 0.1.0 → 1.0.2

package/README.md

@@ -1,164 +1,700 @@
-# @spaps/sdk
+# Sweet Potato SDK
 
-> Sweet Potato Authentication & Payment Service 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)
 
-Zero-config client for SPAPS authentication and payments. Works automatically with local development mode.
+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.
+
+**[📚 Full API Documentation](../API_INTEGRATION_GUIDE.md) | [🛠️ Stripe Admin Guide](../STRIPE_ADMIN_GUIDE.md)**
+
+## 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
+npm install spaps-sdk
 # or
-yarn add @spaps/sdk
+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
 
-```javascript
-import { SPAPSClient } from '@spaps/sdk';
-// or
-const { SPAPSClient } = require('@spaps/sdk');
+### Basic Setup
 
-// Auto-detects local mode - no API key needed for localhost!
-const spaps = new SPAPSClient({
-  apiUrl: 'http://localhost:3300' // Optional, auto-detected
-});
+```typescript
+import { SweetPotatoSDK, TokenManager } from 'spaps-sdk';
 
-// Login
-const { data } = await spaps.login('user@example.com', 'password');
-console.log('User:', data.user);
+// 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
+});
 
-// Check authentication
-if (spaps.isAuthenticated()) {
-  const user = await spaps.getUser();
-  console.log('Current user:', user.data);
-}
+// Auto-restore authentication state (browser only)
+await TokenManager.autoRefreshToken(sdk);
 ```
 
-## Features
+## Authentication Examples
+
+### Wallet Authentication (Complete Flow)
+
+```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);
+```
 
-### 🚀 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
+### Email/Password Authentication
 
-### 🔐 Authentication Methods
-```javascript
-// Email/Password
-await spaps.login(email, password);
-await spaps.register(email, password);
+```typescript
+const authResponse = await sdk.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'securePassword123!'
+});
 
-// Wallet Authentication
-await spaps.walletSignIn(walletAddress, signature, message, 'solana');
+TokenManager.storeTokens(authResponse);
+```
 
-// Token Management
-await spaps.refresh();
-await spaps.logout();
+### Magic Link Authentication
 
-// Get User
-const user = await spaps.getUser();
+```typescript
+await sdk.auth.requestMagicLink({
+  email: 'user@example.com',
+  redirect_url: 'https://myapp.com/auth/callback'
+});
+// User will receive email with authentication link
 ```
 
-### 💳 Stripe Integration
-```javascript
-// Create checkout session
-const session = await spaps.createCheckoutSession(priceId, successUrl);
-window.location.href = session.data.url;
+## Payment Examples
+
+### One-Time Payment
 
-// Manage subscription
-const subscription = await spaps.getSubscription();
-await spaps.cancelSubscription();
+```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'
+  }
+});
+
+// Redirect to Stripe Checkout
+window.location.href = checkoutSession.url!;
 ```
 
-### 📊 Usage Tracking
-```javascript
-// Check balance
-const balance = await spaps.getUsageBalance();
-console.log(`Credits: ${balance.data.balance}`);
+### 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
+  currency: 'usd',
+  quantity: 1,
+  success_url: 'https://myapp.com/success',
+  cancel_url: 'https://myapp.com/cancel'
+});
+```
 
-// Record usage
-await spaps.recordUsage('api-call', 1);
+### 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'
+  }
+});
 ```
 
-## Configuration
+### Product Management
 
-### Production Mode
-```javascript
-const spaps = new SPAPSClient({
-  apiUrl: 'https://api.sweetpotato.com',
-  apiKey: 'spaps_your_api_key_here',
-  timeout: 10000 // Optional timeout in ms
+```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'
+  }
 });
 ```
 
-### Local Development Mode (Auto-detected)
-```javascript
-const spaps = new SPAPSClient();
-// Automatically uses http://localhost:3300 with no API key
+### Subscription Management
+
+```typescript
+// List user subscriptions
+const subscriptions = await sdk.payments.listSubscriptions({
+  status: 'active'
+});
+
+// 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
+});
+
+// Create customer portal session
+const portalSession = await sdk.payments.createCustomerPortalSession({
+  return_url: 'https://myapp.com/account'
+});
+window.location.href = portalSession.url;
 ```
 
-### Environment Variables
-```bash
-# .env
-SPAPS_API_URL=https://api.sweetpotato.com
-SPAPS_API_KEY=spaps_your_api_key_here
+## 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');
+  }
+}
 
-# Next.js
-NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.com
+// 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
+  }
+}
 ```
 
-## Helper Methods
+### Logout
 
-```javascript
-// Check if authenticated
-spaps.isAuthenticated() // boolean
+```typescript
+async function logout() {
+  try {
+    await sdk.auth.logout();
+    TokenManager.clearTokens();
+    console.log('Successfully logged out');
+  } catch (error) {
+    console.error('Logout failed:', error);
+  }
+}
+```
 
-// Get current access token
-spaps.getAccessToken() // string | undefined
+## User Management
 
-// Set access token manually
-spaps.setAccessToken(token)
+### Get Current User
 
-// Check if in local mode
-spaps.isLocalMode() // boolean
+```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
 
-// Health check
-await spaps.health()
+```typescript
+function checkAuthStatus() {
+  if (sdk.auth.isAuthenticated()) {
+    console.log('User is authenticated');
+  } else {
+    console.log('User needs to log in');
+  }
+}
 ```
 
-## Import Styles
+## Utility Functions
+
+### Wallet Address Validation
 
-All these work:
-```javascript
-// ES6 Import
-import { SPAPSClient } from '@spaps/sdk';
-import SPAPSClient from '@spaps/sdk';
+```typescript
+import { WalletUtils } from '@sweet-potato/auth-sdk';
 
-// CommonJS
-const { SPAPSClient } = require('@spaps/sdk');
-const SPAPSClient = require('@spaps/sdk');
+// Detect chain type
+const chainType = WalletUtils.detectChainType('0x742d35Cc6634C0532925a3b8D6Ac6d8F49c3589F');
+console.log(chainType); // 'ethereum'
 
-// Alternative names
-import { SPAPS } from '@spaps/sdk';
-import { SweetPotatoSDK } from '@spaps/sdk';
+// Validate address format
+const isValid = WalletUtils.isValidAddress('0x742d35Cc6634C0532925a3b8D6Ac6d8F49c3589F', 'ethereum');
+console.log(isValid); // true
+
+// Auto-detect and validate
+const isValidAuto = WalletUtils.isValidAddress('0x742d35Cc6634C0532925a3b8D6Ac6d8F49c3589F');
+console.log(isValidAuto); // true
+```
+
+### Token Utilities
+
+```typescript
+// Check if token is expired
+const token = TokenManager.getAccessToken();
+if (token && TokenManager.isTokenExpired(token)) {
+  console.log('Token is expired, refreshing...');
+  await refreshTokens();
+}
 ```
 
 ## Error Handling
 
-```javascript
+```typescript
+import { SweetPotatoAPIError } from '@sweet-potato/auth-sdk';
+
 try {
-  await spaps.login(email, password);
+  await sdk.auth.signInWithPassword({
+    email: 'invalid@example.com',
+    password: 'wrongpassword'
+  });
 } catch (error) {
-  if (error.response?.status === 401) {
-    console.error('Invalid credentials');
-  } else if (error.response?.status === 429) {
-    console.error('Rate limited');
+  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');
+    }
+  }
+}
+```
+
+## Advanced Usage
+
+### Custom Requests
+
+```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);
+  }
+}
+```
+
+### Health Check
+
+```typescript
+async function checkAPIHealth() {
+  const isHealthy = await sdk.healthCheck();
+  if (isHealthy) {
+    console.log('API is healthy');
   } else {
-    console.error('Error:', error.message);
+    console.log('API is down or unreachable');
   }
 }
 ```
 
+## React Integration Example
+
+```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
+  };
+}
+```
+
+## Configuration Options
+
+```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)
+}
+```
+
+## 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';
+```
+
+## 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'
+});
+
+// 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
+  })
+});
+```
+
+### Admin Operations
+❌ **Not available:** `sdk.admin.*` methods
+
+Admin operations require JWT authentication:
+- Application management (create/rotate API keys)
+- User management (admin dashboard)  
+- Direct database operations
+- Product sync from Stripe
+
+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
+
+See [Stripe Admin Guide](../STRIPE_ADMIN_GUIDE.md) for product management instructions.
+
+## Local Development Mode
+
+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
+
+```bash
+# Start local server
+npx spaps local
+
+# Your app can now connect to:
+http://localhost:3456
+```
+
+## Production Notes
+
+⚠️ **Production API is not yet available.** Currently, only local development mode is supported.
+
+Future production URL: `https://api.sweetpotato.dev` (coming soon)
+
+## Troubleshooting
+
+### Common Issues
+
+**Wrong Port**
+```typescript
+// ❌ Wrong
+apiUrl: 'http://localhost:3000'
+apiUrl: 'http://localhost:3300'
+
+// ✅ Correct - always use 3456
+apiUrl: 'http://localhost:3456'
+```
+
+**CORS Errors**
+```typescript
+// In local mode, CORS is enabled for all origins
+// In production, ensure your domain is whitelisted
+```
+
+**Token Expired**
+```typescript
+// Use TokenManager for automatic refresh
+await TokenManager.autoRefreshToken(sdk);
+```
+
+**Rate Limiting**
+```typescript
+// SDK automatically retries with exponential backoff
+// Configure retries in SDK initialization
+const sdk = new SweetPotatoSDK({
+  apiUrl: '...',
+  apiKey: '...',
+  retries: 5 // Increase retry count
+});
+```
+
+## Migration Guide
+
+### From v0.x to v1.0
+
+```typescript
+// Old (v0.x)
+const sdk = new SweetPotatoSDK(apiUrl, apiKey);
+
+// New (v1.0)
+const sdk = new SweetPotatoSDK({
+  apiUrl,
+  apiKey,
+  timeout: 30000,
+  retries: 3
+});
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## Security
+
+- **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
+
+## Support
+
+- 📖 [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)
+
 ## License
 
-MIT
+MIT © Sweet Potato Team