@explorins/pers-sdk 1.3.5 → 1.3.7

package/README.md

@@ -1,15 +1,13 @@
-# PERS SDK
+# @explorins/pers-sdk
 
-Platform-agnostic TypeScript SDK for the PERS (Phygital Experience Rewards System) API.
+[![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)
 
-## Features
+**Platform-agnostic TypeScript SDK for PERS (Phygital Experience Rewards System)** - Core SDK providing domain-driven business logic and API integration for tourism loyalty applications.
 
-- **Platform Agnostic**: Works across web, mobile, and server environments
-- **Automatic Authentication**: Intelligent token management with proactive refresh
-- **Background Refresh**: Non-blocking token refresh for optimal performance
-- **TypeScript Support**: Full type safety with comprehensive interfaces
-- **Error Handling**: Robust error handling with retry mechanisms
-- **Production Ready**: Optimized defaults for production environments
+## PERS Ecosystem
+
+PERS is a comprehensive tourism loyalty platform bridging physical and digital experiences through loyalty programs, campaign management, payments, blockchain integration, business management, and analytics.
 
 ## Installation
 
@@ -17,399 +15,169 @@ Platform-agnostic TypeScript SDK for the PERS (Phygital Experience Rewards Syste
 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, or custom frameworks
+
 ## Quick Start
 
 ### Basic Setup
 
 ```typescript
-import { createPersSDK, createAuthProvider } from '@explorins/pers-sdk/core';
-import { BrowserHttpClient } from '@explorins/pers-sdk/browser'; // or your HTTP client
-
-// Create auth provider
-const authProvider = createAuthProvider({
-  authType: 'user',
-  tokenProvider: () => getFirebaseToken(), // Your token provider
-  projectKey: 'your-project-key'
-});
+import { PersApiClient } from '@explorins/pers-sdk/core';
+
+// Custom HTTP client (platform-specific)
+const httpClient = {
+  get: async (url: string) => fetch(url).then(r => r.json()),
+  post: async (url: string, data: any) => 
+    fetch(url, { method: 'POST', body: JSON.stringify(data) }).then(r => r.json()),
+  put: async (url: string, data: any) => 
+    fetch(url, { method: 'PUT', body: JSON.stringify(data) }).then(r => r.json()),
+  delete: async (url: string) => 
+    fetch(url, { method: 'DELETE' }).then(r => r.json())
+};
 
-// Create SDK instance
-const sdk = createPersSDK(new BrowserHttpClient(), {
+// Create API client
+const apiClient = new PersApiClient(httpClient, {
   environment: 'production',
-  apiProjectKey: 'your-project-key',
-  authProvider
+  apiVersion: 'v2',
+  apiProjectKey: 'your-project-key'
 });
 
-// Use the API client
-const apiClient = sdk.api();
+// Login with external JWT (Firebase, Auth0, etc.)
+const result = await apiClient.loginUser(firebaseJWT);
 ```
 
-### Authentication
-
-#### User Authentication
+### Platform Examples
 
-```typescript
-// Login user with external JWT (Firebase, Auth0, etc.)
-const firebaseToken = await getIdToken();
-const session = await apiClient.loginUser(firebaseToken);
-
-console.log('User authenticated:', session.user.email);
-```
-
-#### Admin Authentication
+#### Angular
 
 ```typescript
-// Login admin with external JWT
-const adminToken = await getAdminToken();
-const session = await apiClient.loginAdmin(adminToken);
+import { PERS_ANGULAR_SDK_SERVICE } from '@explorins/pers-sdk-angular';
 
-console.log('Admin authenticated:', session.user.email);
-```
-
-### Making API Calls
+@Injectable()
+export class AuthService {
+  private persSDK = inject(PERS_ANGULAR_SDK_SERVICE);
 
-#### GET Requests
-
-```typescript
-// Fetch user data
-const user = await apiClient.get<User>('/users/me');
-
-// Download file
-const csvData = await apiClient.get('/export/data.csv', 'blob');
-```
-
-#### POST Requests
-
-```typescript
-// Create resource
-const newUser = await apiClient.post<User>('/users', {
-  name: 'John Doe',
-  email: 'john@example.com'
-});
-
-// Public endpoint (bypass auth)
-const contact = await apiClient.post('/public/contact', formData, {
-  bypassAuth: true
-});
+  async login(firebaseToken: string) {
+    return this.persSDK.api().loginUser(firebaseToken);
+  }
+}
 ```
 
-#### PUT/DELETE Requests
-
-```typescript
-// Update resource
-const updatedUser = await apiClient.put<User>('/users/123', userData);
+#### React Native
 
-// Delete resource
-await apiClient.delete('/users/123');
-```
-
-## Configuration
+```tsx
+import { usePersSDK } from '@explorins/pers-sdk-react-native';
 
-### Basic Configuration
-
-```typescript
-const config = {
-  environment: 'production',           // 'development' | 'staging' | 'production'
-  apiProjectKey: 'your-project-key',  // Required for API access
-  apiVersion: 'v2',                   // 'v1' | 'v1.8' | 'v1.9' | 'v2'
-  timeout: 30000,                     // Request timeout (ms)
-  retries: 3,                         // Retry attempts
-  authProvider                        // Authentication provider
-};
-```
-
-### Advanced Configuration
-
-```typescript
-const config = {
-  // ... basic config
+function LoginScreen() {
+  const { login } = usePersSDK();
   
-  // Token refresh settings
-  tokenRefreshMargin: 120,          // Refresh tokens 2 minutes before expiry
-  backgroundRefreshThreshold: 30,    // Use background refresh if >30s remaining
-};
-```
-
-## Authentication Providers
-
-### Simple Token Provider
-
-```typescript
-const authProvider = createAuthProvider({
-  authType: 'user',
-  token: 'static-token',            // Static token
-  projectKey: 'your-project-key'
-});
+  const handleLogin = async () => {
+    await login(firebaseToken);
+  };
+}
 ```
 
-### Dynamic Token Provider
+## Domain Architecture
 
 ```typescript
-const authProvider = createAuthProvider({
-  authType: 'user',
-  tokenProvider: async () => {
-    // Fetch fresh token from your auth system
-    return await getFirebaseToken();
-  },
-  projectKey: 'your-project-key',
-  
-  // Optional: Handle token refresh
-  onTokenExpired: async () => {
-    console.log('Token expired - refreshing...');
-  },
-  
-  // Optional: React to token refresh
-  onTokenRefreshed: (newToken) => {
-    console.log('New token received');
-  }
-});
+// Domain-specific imports (recommended)
+import { PersApiClient } from '@explorins/pers-sdk/core';
+import { TokenSDK } from '@explorins/pers-sdk/token';
+import { createBusinessSDK } from '@explorins/pers-sdk/business';
+import { createCampaignSDK } from '@explorins/pers-sdk/campaign';
 ```
 
-### Custom Storage
+## Core Authentication
 
 ```typescript
-const authProvider = createAuthProvider({
-  authType: 'user',
-  tokenProvider: () => getToken(),
-  projectKey: 'your-project-key',
-  tokenStorage: 'localStorage', // 'localStorage' | 'memory' | 'sessionStorage'
-  
-  // Or custom storage
-  customTokenStorage: {
-    setItem: async (key, value) => await customStorage.set(key, value),
-    getItem: async (key) => await customStorage.get(key),
-    removeItem: async (key) => await customStorage.remove(key)
-  }
-});
-```
-
-## Token Management
-
-### Token Lifecycle
-
-The SDK automatically handles token lifecycle:
-
-1. **Proactive Refresh**: Tokens are refreshed before expiry
-2. **Background Refresh**: Non-blocking refresh for optimal performance
-3. **Fallback Refresh**: Reactive refresh if proactive refresh fails
-4. **Provider Token**: Automatic fallback to provider token if refresh tokens expire
-
-### Manual Token Checks
+// Login with external JWT
+const authResult = await apiClient.loginUser(externalJWT);
 
-```typescript
-// Check if user is authenticated
+// Check authentication status
 if (apiClient.hasValidAuth()) {
   console.log('User is authenticated');
 }
 
-// Check token expiry
-if (await apiClient.isTokenExpired(120)) {
-  console.log('Token expires within 2 minutes');
-}
-
-// Check if full re-authentication is needed
-if (await apiClient.areAllTokensExpired()) {
-  console.log('Full re-authentication required');
-  redirectToLogin();
-}
-```
-
-## Error Handling
-
-### API Errors
-
-```typescript
-import { PersApiError } from '@explorins/pers-sdk/core';
-
-try {
-  const data = await apiClient.get('/protected-endpoint');
-} catch (error) {
-  if (error instanceof PersApiError) {
-    console.error('API Error:', error.message);
-    console.error('Status:', error.status);
-    console.error('Endpoint:', error.endpoint);
-    console.error('Retryable:', error.retryable);
-  }
-}
-```
-
-### Authentication Errors
-
-Authentication failures are handled automatically, but you can listen for events:
-
-```typescript
-// The SDK will automatically attempt refresh and fallback strategies
-// If all authentication methods fail, API calls will throw appropriate errors
-```
-
-## TypeScript Support
-
-### Type Definitions
+// Automatic token refresh handled internally
+await apiClient.refreshToken();
 
-```typescript
-import { 
-  PersApiClient, 
-  PersConfig, 
-  PersAuthProvider,
-  PersEnvironment,
-  PersApiVersion 
-} from '@explorins/pers-sdk/core';
-
-// Custom interfaces
-interface User {
-  id: string;
-  email: string;
-  name: string;
-}
-
-// Typed API calls
-const user = await apiClient.get<User>('/users/me');
-const users = await apiClient.get<User[]>('/users');
+// Clear authentication
+await apiClient.clearAuth();
 ```
 
-### Custom Auth Provider
+## Business Domain Examples
 
+### Token Management
 ```typescript
-import { PersAuthProvider, AuthType } from '@explorins/pers-sdk/core';
+import { TokenSDK } from '@explorins/pers-sdk/token';
 
-class CustomAuthProvider implements PersAuthProvider {
-  authType: AuthType = 'user';
-  
-  async getToken(): Promise<string | null> {
-    // Your implementation
-    return await this.tokenManager.getAccessToken();
-  }
-  
-  async getProjectKey(): Promise<string | null> {
-    return 'your-project-key';
-  }
-  
-  // Implement other required methods...
-}
+const tokenSDK = new TokenSDK(apiClient);
+const balances = await tokenSDK.getBalances(userId);
 ```
 
-## Platform Integration
-
-### Browser (React, Vue, etc.)
-
+### Business Operations
 ```typescript
-import { BrowserHttpClient } from '@explorins/pers-sdk/browser';
+import { createBusinessSDK } from '@explorins/pers-sdk/business';
 
-const sdk = createPersSDK(new BrowserHttpClient(), config);
+const businessSDK = createBusinessSDK(apiClient);
+const businesses = await businessSDK.listBusinesses();
 ```
 
-### Node.js
-
+### Campaign Management
 ```typescript
-import { NodeHttpClient } from '@explorins/pers-sdk/node';
+import { createCampaignSDK } from '@explorins/pers-sdk/campaign';
 
-const sdk = createPersSDK(new NodeHttpClient(), config);
+const campaignSDK = createCampaignSDK(apiClient);
+const campaigns = await campaignSDK.getActiveCampaigns();
 ```
 
-### React Native
-
-```typescript
-import { ReactNativeHttpClient } from '@explorins/pers-sdk/react-native';
-
-const sdk = createPersSDK(new ReactNativeHttpClient(), config);
-```
+## Available Domains
 
-## Best Practices
+- `/core` - Core API client and authentication
+- `/token` - Token balances and transfers
+- `/business` - Business operations and management
+- `/campaign` - Marketing campaigns and challenges
+- `/transaction` - Payment and transaction history
+- `/redemption` - Reward redemption system
+- `/payment` - Payment processing
+- `/user` - User profile management
+- `/web3` - Blockchain and wallet integration
+- `/analytics` - Reporting and analytics
+- `/tenant` - Multi-tenant management
 
-### 1. Environment Configuration
+## Configuration
 
 ```typescript
-// Use environment variables
 const config = {
-  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
-  apiProjectKey: process.env.PERS_PROJECT_KEY,
+  environment: 'production',      // 'development' | 'staging' | 'production'
+  apiVersion: 'v2',              // 'v1' | 'v1.8' | 'v1.9' | 'v2'
+  apiProjectKey: 'your-key',     // Required: Your PERS project key
+  timeout: 30000,                // Request timeout (default: 30s)
+  retries: 3                     // Retry attempts (default: 3)
 };
 ```
 
-### 2. Error Boundaries
-
-```typescript
-// Wrap API calls in try-catch blocks
-const fetchUserData = async () => {
-  try {
-    return await apiClient.get<User>('/users/me');
-  } catch (error) {
-    // Handle error appropriately
-    logError(error);
-    showErrorToast('Failed to load user data');
-    return null;
-  }
-};
-```
-
-### 3. Token Provider Caching
-
-```typescript
-let cachedToken: string | null = null;
-
-const authProvider = createAuthProvider({
-  tokenProvider: async () => {
-    if (!cachedToken) {
-      cachedToken = await getFirebaseToken();
-    }
-    return cachedToken;
-  },
-  onTokenRefreshed: (newToken) => {
-    cachedToken = newToken; // Update cache
-  }
-});
-```
-
-## Migration Guide
-
-### From v1.x to v2.x
-
-The v2 SDK introduces a cleaner, more maintainable architecture:
-
-```typescript
-// v1.x (Legacy)
-import { PersSDK } from '@explorins/pers-sdk';
-const sdk = new PersSDK(config);
-
-// v2.x (Current)
-import { createPersSDK, createAuthProvider } from '@explorins/pers-sdk/core';
-import { BrowserHttpClient } from '@explorins/pers-sdk/browser';
-
-const authProvider = createAuthProvider(authConfig);
-const sdk = createPersSDK(new BrowserHttpClient(), {
-  ...config,
-  authProvider
-});
-```
-
-## API Reference
-
-### Core Classes
-
-- **`PersApiClient`** - Main API client for authenticated requests
-- **`PersSDK`** - SDK wrapper providing access to API client
-- **`createAuthProvider()`** - Factory for creating authentication providers
-- **`createPersSDK()`** - Factory for creating SDK instances
-
-### Interfaces
-
-- **`PersConfig`** - SDK configuration options
-- **`PersAuthProvider`** - Authentication provider interface
-- **`AuthTokens`** - Token structure definition
-- **`SimpleAuthConfig`** - Simple auth provider configuration
+## Dependencies
 
-### Types
+- **`@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)
 
-- **`PersEnvironment`** - API environment options
-- **`PersApiVersion`** - Supported API versions
-- **`AuthType`** - Authentication types ('user' | 'admin')
+## Related Packages
 
-## Support
+- [@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
 
-For issues, feature requests, or questions:
+## Documentation
 
-1. Check the [documentation](https://docs.pers.ninja)
-2. Search [existing issues](https://github.com/explorins/pers-sdk/issues)
-3. Create a [new issue](https://github.com/explorins/pers-sdk/issues/new)
+For comprehensive API documentation, usage guides, and examples, visit the [PERS SDK Documentation](https://docs.pers.ninja).
 
 ## License