@explorins/pers-sdk 1.6.6 → 1.6.10

package/README.md

@@ -3,18 +3,9 @@
 [![npm version](https://badge.fury.io/js/%40explorins%2Fpers-sdk.svg)](https://badge.fury.io/js/%40explorins%2Fpers-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Platform-agnostic TypeScript SDK for PERS (Phygital Experience Rewards System)** - Modern Manager-Service architecture providing clean, consistent APIs for tourism loyalty applications.
+Platform-agnostic TypeScript SDK for PERS (Phygital Experience Rewards System) - Modern Manager-Service architecture providing clean, consistent APIs for tourism loyalty applications.
 
-## 🚀 What's New in v1.6.6+
-
-**🎯 Complete Architecture Refactoring**
-- **Clean Manager Pattern**: All 15 domain managers use consistent Service-based architecture
-- **Legacy Pattern Removal**: Eliminated all factory functions for cleaner, predictable patterns  
-- **Performance Optimized**: 29% faster builds, reduced bundle size, internal token refresh
-- **Zero Breaking Changes**: Manager interface remains identical for seamless upgrades
-- **Enhanced Documentation**: Comprehensive guides with practical examples
-
-## PERS Ecosystem
+## Overview
 
 PERS is a comprehensive tourism loyalty platform bridging physical and digital experiences through loyalty programs, campaign management, payments, blockchain integration, business management, and analytics.
 
@@ -24,43 +15,7 @@ PERS is a comprehensive tourism loyalty platform bridging physical and digital e
 npm install @explorins/pers-sdk
 ```
 
-## Platform Integration
-
-- **[@explorins/pers-sdk-angular](https://www.npmjs.com/package/@explorins/pers-sdk-angular)** - Angular dependency injection wrapper
-- **[@explorins/pers-sdk-react-native](https://www.npmjs.com/package/@explorins/pers-sdk-react-native)** - React Native providers and hooks  
-- **Direct Integration** - Node.js, Vanilla JS, React, Vue, or custom frameworks
-
-## 🏗️ Architecture Overview
-
-```typescript
-PERS SDK v1.6.6 - Clean Manager Pattern Architecture
-├── 🎯 Manager Layer (Primary Interface)
-│   ├── auth: AuthManager           // Authentication & sessions
-│   ├── users: UserManager          // User profiles & management
-│   ├── tokens: TokenManager        // Token operations & balances
-│   ├── businesses: BusinessManager // Business operations
-│   ├── campaigns: CampaignManager  // Marketing campaigns
-│   ├── redemptions: RedemptionManager // Reward redemptions
-│   ├── transactions: TransactionManager // Transaction history
-│   ├── purchases: PurchaseManager    // Payment processing  
-│   ├── analytics: AnalyticsManager // Reporting & insights
-│   ├── tenants: TenantManager      // Multi-tenant config
-│   ├── donations: DonationManager  // Charitable giving
-│   ├── files: FileManager         // File operations
-│   └── web3: Web3Manager          // Blockchain operations
-├── ⚙️ Service Layer (Advanced Access)
-│   ├── Business logic & operations
-│   └── Direct service method access via getXService()
-└── 🚀 Core Infrastructure
-    ├── PersApiClient (HTTP + auth)
-    └── Platform adapters
-```
-
-## ⚡ Quick Start
-
-### 1. Choose Your Integration Method
-
-#### 🎯 **Recommended: Manager Pattern**
+## Quick Start
 
 ```typescript
 import { PersSDK } from '@explorins/pers-sdk';
@@ -71,58 +26,49 @@ const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
   apiProjectKey: 'your-project-key'
 });
 
-// Clean, intuitive manager interface
+// Authentication
 const user = await sdk.auth.getCurrentUser();
-const campaigns = await sdk.campaigns.getActiveCampaigns();
-const tokens = await sdk.tokens.getTokens();
-```
 
-#### ⚙️ **Advanced: Service Layer Access**
+// Business operations
+const businesses = await sdk.businesses.getActiveBusinesses();
 
-```typescript
-// Access services directly for advanced operations
-const userService = sdk.users.getUserService();
-const campaignService = sdk.campaigns.getCampaignService();
+// Campaign management
+const campaigns = await sdk.campaigns.getActiveCampaigns();
+const campaignClaim = await sdk.campaigns.claimCampaign({ campaignId: 'campaign-123', userId: 'user-456' });
 
-// Use service methods directly
-const advancedUserData = await userService.getSomeAdvancedMethod();
-const campaignMetrics = await campaignService.getDetailedCampaignMetrics();
+// Token operations
+const tokens = await sdk.tokens.getTokens();
+const balances = await sdk.tokens.getBalances(userId);
 ```
 
-### 2. Platform-Specific Setup
+## Platform Integration
 
-#### Angular Integration
+### Angular
 
 ```typescript
-// app.config.ts
-import { provideHttpClient } from '@angular/common/http';
-import { PersSDKService } from 'your-app/services/pers-sdk.service';
-
-export const appConfig = {
-  providers: [
-    provideHttpClient(),
-    PersSDKService
-  ]
-};
-
-// pers-sdk.service.ts
 import { Injectable } from '@angular/core';
 import { HttpClient } from '@angular/common/http';
 import { PersSDK } from '@explorins/pers-sdk';
 import { AngularHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
 
 @Injectable({ providedIn: 'root' })
-export class PersSDKService extends PersSDK {
+export class PersSDKService {
+  private sdk: PersSDK;
+
   constructor(httpClient: HttpClient) {
-    super(new AngularHttpClientAdapter(httpClient), {
+    this.sdk = new PersSDK(new AngularHttpClientAdapter(httpClient), {
       environment: 'production',
       apiProjectKey: 'your-project-key'
     });
   }
+
+  getSDK(): PersSDK {
+    return this.sdk;
+  }
 }
 ```
 
-#### React/Browser Setup
+### React/Browser
 
 ```typescript
 import { PersSDK } from '@explorins/pers-sdk';
@@ -132,14 +78,9 @@ const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
   environment: 'production',
   apiProjectKey: 'your-project-key'
 });
-
-// React Hook example
-export function usePersSDK() {
-  return sdk;
-}
 ```
 
-#### Node.js Setup
+### Node.js
 
 ```typescript
 import { PersSDK } from '@explorins/pers-sdk';
@@ -151,207 +92,77 @@ const sdk = new PersSDK(new NodeHttpClientAdapter(), {
 });
 ```
 
-## 📋 Domain Managers API Reference
-
-### 🔐 Authentication Manager
-
-```typescript
-// Login with external JWT (Firebase, Auth0, etc.)
-const authResult = await sdk.auth.loginWithToken(jwtToken, 'user');
-const adminResult = await sdk.auth.loginWithToken(adminJWT, 'admin');
-
-// Check authentication status
-const isAuthenticated = await sdk.auth.isAuthenticated();
-const hasValidAuth = sdk.auth.hasValidAuth();
-
-// User management
-const currentUser = await sdk.auth.getCurrentUser();
-
-// Token management
-const newTokens = await sdk.auth.refreshTokens();
-await sdk.auth.clearAuth();
-```
-
-### 👤 User Manager
-
-```typescript
-// Current user operations
-const user = await sdk.users.getCurrentUser();
-await sdk.users.updateCurrentUser(userData);
-
-// User lookup
-const userById = await sdk.users.getUserById(identifier);
-const publicProfiles = await sdk.users.getAllUsersPublic();
-
-// Admin operations
-const allUsers = await sdk.users.getAllUsers();
-await sdk.users.updateUser(userId, userData);
-await sdk.users.toggleUserStatus(user);
-```
-
-### 🪙 Token Manager
-
-```typescript
-// Token operations
-const tokens = await sdk.tokens.getTokens();
-const creditToken = await sdk.tokens.getActiveCreditToken();
-const rewardTokens = await sdk.tokens.getRewardTokens();
-
-// Balance operations
-const balances = await sdk.tokens.getBalances(userId);
-await sdk.tokens.transferTokens(transferData);
-```
-
-### 🏢 Business Manager
-
-```typescript
-// Public business operations
-const businesses = await sdk.businesses.getActiveBusinesses();
-const business = await sdk.businesses.getBusinessById(id);
-const types = await sdk.businesses.getBusinessTypes();
-
-// Admin operations
-const allBusinesses = await sdk.businesses.getBusinesses();
-await sdk.businesses.createBusiness(businessData);
-await sdk.businesses.updateBusiness(id, businessData);
-```
-
-### 🎯 Campaign Manager
-
-```typescript
-// Public campaign operations
-const campaigns = await sdk.campaigns.getActiveCampaigns();
-const campaign = await sdk.campaigns.getCampaignById(id);
-
-// User operations
-await sdk.campaigns.claimCampaign(claimData);
-const userClaims = await sdk.campaigns.getUserClaims();
-
-// Admin operations
-const allCampaigns = await sdk.campaigns.getAllCampaigns();
-await sdk.campaigns.createCampaign(campaignData);
-await sdk.campaigns.toggleCampaignStatus(campaignId);
-
-// Advanced operations
-const triggers = await sdk.campaigns.getCampaignTriggers();
-await sdk.campaigns.setCampaignTrigger(campaignId, triggerId);
-```
-
-### 🎁 Redemption Manager
-
-```typescript
-// Public redemption operations
-const redemptions = await sdk.redemptions.getActiveRedemptions();
-const types = await sdk.redemptions.getRedemptionTypes();
-
-// User operations
-await sdk.redemptions.redeemOffer(redemptionId);
-const userRedemptions = await sdk.redemptions.getUserRedemptions();
-
-// Admin operations
-const allRedemptions = await sdk.redemptions.getAllRedemptions();
-await sdk.redemptions.createRedemption(redemptionData);
-await sdk.redemptions.toggleRedemptionStatus(redemptionId);
-```
+## Architecture
 
-### 💳 Payment Manager
+The SDK uses a clean Manager-Service pattern:
 
 ```typescript
-// Payment operations
-const intent = await sdk.payments.createPaymentIntent(100, 'usd', 'email', 'desc');
-const tokens = await sdk.payments.getActivePurchaseTokens();
-const purchases = await sdk.payments.getAllUserPurchases();
-```
+// Manager Layer (Primary Interface)
+sdk.auth           // Authentication & sessions
+sdk.users          // User profiles & management
+sdk.tokens         // Token operations & balances
+sdk.businesses     // Business operations
+sdk.campaigns      // Marketing campaigns
+sdk.redemptions    // Reward redemptions
+sdk.transactions   // Transaction history
+sdk.payments       // Payment processing
+sdk.analytics      // Reporting & insights
+sdk.tenants        // Multi-tenant configuration
+sdk.donations      // Charitable giving
+sdk.files          // File operations
+sdk.web3           // Blockchain operations
 
-### 📊 Transaction Manager
-
-```typescript
-// Transaction operations
-const transaction = await sdk.transactions.getTransactionById(id);
-await sdk.transactions.createTransaction(transactionData);
-const history = await sdk.transactions.getUserTransactionHistory('all');
+// Service Layer (Advanced Access)
+sdk.users.getUserService()     // Direct service access
+sdk.campaigns.getCampaignService()
 ```
 
-### 🏢 Tenant Manager
+## Core Features
 
-```typescript
-// Tenant configuration
-const tenantInfo = await sdk.tenants.getTenantInfo();
-const clientConfig = await sdk.tenants.getClientConfig();
-const loginToken = await sdk.tenants.getLoginToken();
-
-// Admin operations
-await sdk.tenants.updateTenant(tenantData);
-const admins = await sdk.tenants.getAdmins();
-await sdk.tenants.createAdmin(adminData);
-```
+### Authentication
+- External JWT integration (Firebase, Auth0, etc.)
+- Native token validation and refresh
+- User and admin authentication flows
 
-### 📈 Analytics Manager
+### Business Management
+- Business registration and profiles
+- Business type management
+- Public business discovery
 
-```typescript
-// Transaction analytics
-const analytics = await sdk.analytics.getTransactionAnalytics({
-  startDate: '2024-01-01',
-  endDate: '2024-12-31',
-  groupBy: 'month'
-});
-```
+### Campaign System
+- Marketing campaign management
+- User campaign claims and participation
+- Advanced campaign triggers and automation
 
-### 💝 Donations Manager
+### Token Economy
+- Token balance management
+- Token transfers and transactions
+- Multiple token type support
 
-```typescript
-// Donation types management
-const donationTypes = await sdk.donations.getDonationTypes();
-```
+### Reward Redemptions
+- Redemption offer management
+- User redemption tracking
+- Multiple redemption types
 
-## 🔧 Advanced Usage
+### Payment Processing
+- Payment intent creation
+- Purchase token management
+- Transaction history
 
-### Custom HTTP Client
+## Configuration
 
 ```typescript
-import { HttpClient, RequestOptions } from '@explorins/pers-sdk/core';
-
-class CustomHttpClient implements HttpClient {
-  async get<T>(url: string, options?: RequestOptions): Promise<T> {
-    // Your custom implementation
-  }
-  
-  async post<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T> {
-    // Your custom implementation
-  }
-  
-  async put<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T> {
-    // Your custom implementation  
-  }
-  
-  async delete<T>(url: string, options?: RequestOptions): Promise<T> {
-    // Your custom implementation
-  }
+interface PersConfig {
+  environment?: 'development' | 'staging' | 'production';
+  apiVersion?: 'v2';
+  apiProjectKey: string;
+  timeout?: number;
+  retries?: number;
+  authProvider?: PersAuthProvider;
 }
-
-const sdk = new PersSDK(new CustomHttpClient(), config);
-```
-
-### Direct API Access
-
-```typescript
-// For operations not covered by managers
-const apiClient = sdk.api();
-
-// Custom endpoints
-const customData = await apiClient.get<CustomType>('/custom-endpoint');
-await apiClient.post('/custom-endpoint', customData);
-
-// Direct authentication methods (advanced usage)
-const userSession = await apiClient.loginUser(firebaseJWT);
-const adminSession = await apiClient.loginAdmin(adminJWT);
-
-// Advanced auth operations
-const isExpired = await apiClient.isTokenExpired(120);
-const allExpired = await apiClient.areAllTokensExpired();
 ```
 
-### Error Handling
+## Error Handling
 
 ```typescript
 import { PersApiError } from '@explorins/pers-sdk/core';
@@ -361,120 +172,32 @@ try {
 } catch (error) {
   if (error instanceof PersApiError) {
     console.error('PERS API Error:', error.message, error.statusCode);
-  } else {
-    console.error('Unknown error:', error);
   }
 }
 ```
 
-## 📦 Available Modules
-
-### Core Modules
-- `/core` - Core API client and authentication
-- `/platform-adapters` - Ready-to-use HTTP client adapters
+## Bundle Size
 
-### Domain Modules
-- `/business` - Business operations and management
-- `/campaign` - Marketing campaigns and challenges  
-- `/redemption` - Reward redemption system
-- `/token` - Token balances and transfers
-- `/transaction` - Payment and transaction history
-- `/payment` - Payment processing
-- `/user` - User profile management
-- `/analytics` - Reporting and analytics
-- `/tenant` - Multi-tenant management
-- `/donation` - Donation management
-- `/web3` - Blockchain and wallet integration
-- `/web3-chain` - Web3 chain operations
+- Core SDK: ~85 KB (minified)
+- Tree-shaking friendly
+- Zero external authentication dependencies
+- Native browser API implementation
 
-## ⚙️ Configuration
-
-```typescript
-interface PersConfig {
-  environment: 'development' | 'staging' | 'production';
-  apiVersion?: 'v1' | 'v1.8' | 'v1.9' | 'v2';
-  apiProjectKey: string;
-  timeout?: number;          // Request timeout (default: 30s)  
-  retries?: number;          // Retry attempts (default: 3)
-  authProvider?: PersAuthProvider;  // Custom auth provider
-}
-```
+## Documentation
 
-## 🔄 Migration Guide
+For comprehensive documentation, examples, and advanced usage:
 
-### From Legacy SDK to Manager Pattern
-
-**Before (Legacy):**
-```typescript
-const businessSDK = createBusinessSDK(apiClient);
-const businesses = await businessSDK.getActiveBusinesses();
-```
-
-**After (Manager Pattern):**
-```typescript
-const sdk = new PersSDK(httpClient, config);
-const businesses = await sdk.businesses.getActiveBusinesses();
-```
-
-### Authentication API Changes (v1.6+)
-
-**Manager API (Recommended):**
-```typescript
-// Unified authentication method
-const authResult = await sdk.auth.loginWithToken(jwtToken, 'user');
-const adminResult = await sdk.auth.loginWithToken(jwtToken, 'admin');
-```
-
-**Core API (Advanced):**
-```typescript
-// Separate methods still available for direct API access
-const userResult = await sdk.api().loginUser(jwtToken);
-const adminResult = await sdk.api().loginAdmin(jwtToken);
-```
-
-**Benefits:**
-- ✅ Cleaner API surface at manager level
-- ✅ Better TypeScript inference
-- ✅ Consistent error handling  
-- ✅ Easier testing and mocking
-- ✅ Future-proof architecture
-- ✅ Backward compatibility maintained in core API
-
-## 📊 Bundle Size
-
-- **Core SDK**: ~90 KB (minified)
-- **Individual domains**: 2-20 KB each
-- **Manager pattern**: Minimal overhead (~5 KB)
-- **Tree-shaking friendly**: Import only what you need
-
-## 🧪 Testing
-
-```typescript
-// Mock manager for testing
-const mockUserManager = {
-  getCurrentUser: jest.fn().mockResolvedValue(mockUser),
-  updateCurrentUser: jest.fn().mockResolvedValue(updatedUser)
-};
-
-const sdk = {
-  users: mockUserManager
-} as jest.Mocked<PersSDK>;
-```
+**[https://docs.pers.ninja/1.intro](https://docs.pers.ninja/1.intro)**
 
-## Dependencies
+For detailed API reference:
 
-- **`@explorins/web3-ts`** (^0.3.75) - Web3 blockchain integration  
-- **`jwt-decode`** (^4.0.0) - JWT token parsing
-- **`@explorins/pers-shared`** (*) - Shared types (peer dependency)
-- **`ethers`** (^6.15.0) - Ethereum integration (peer dependency)
+**[https://docs.pers.ninja/sdk](https://docs.pers.ninja/sdk)** (Interactive API Documentation)
 
 ## Related Packages
 
-- [@explorins/pers-sdk-angular](https://www.npmjs.com/package/@explorins/pers-sdk-angular) - Angular integration
-- [@explorins/pers-sdk-react-native](https://www.npmjs.com/package/@explorins/pers-sdk-react-native) - React Native integration  
-- [@explorins/pers-shared](https://www.npmjs.com/package/@explorins/pers-shared) - Shared types and DTOs
-- [@explorins/web3-ts](https://www.npmjs.com/package/@explorins/web3-ts) - Web3 utilities
+- [@explorins/pers-sdk-react-native](https://www.npmjs.com/package/@explorins/pers-sdk-react-native) - React Native integration
+- [@explorins/pers-shared](https://www.npmjs.com/package/@explorins/pers-shared) - Shared types and utilities
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License