@explorins/pers-sdk 1.3.16 → 1.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +351 -81
  2. package/dist/chunks/base-token-service-D0KANDgM.js +139 -0
  3. package/dist/chunks/base-token-service-D0KANDgM.js.map +1 -0
  4. package/dist/chunks/base-token-service-zNfPjHRx.cjs +141 -0
  5. package/dist/chunks/base-token-service-zNfPjHRx.cjs.map +1 -0
  6. package/dist/chunks/{pers-sdk-DiwCwBiC.cjs → pers-sdk-CI2YXKb_.cjs} +1335 -50
  7. package/dist/chunks/pers-sdk-CI2YXKb_.cjs.map +1 -0
  8. package/dist/chunks/{pers-sdk-Rc8YKyNc.js → pers-sdk-CVSAFBLh.js} +1325 -51
  9. package/dist/chunks/pers-sdk-CVSAFBLh.js.map +1 -0
  10. package/dist/chunks/{base-token-service-BA81_Ouq.js → token-sdk-BW4kkJb3.js} +2 -137
  11. package/dist/chunks/token-sdk-BW4kkJb3.js.map +1 -0
  12. package/dist/chunks/{base-token-service-BQ6uFoki.cjs → token-sdk-CiAbOb6c.cjs} +1 -137
  13. package/dist/chunks/token-sdk-CiAbOb6c.cjs.map +1 -0
  14. package/dist/core/index.d.ts +1 -0
  15. package/dist/core/index.d.ts.map +1 -1
  16. package/dist/core.cjs +22 -1
  17. package/dist/core.cjs.map +1 -1
  18. package/dist/core.js +11 -1
  19. package/dist/core.js.map +1 -1
  20. package/dist/index.cjs +21 -5
  21. package/dist/index.cjs.map +1 -1
  22. package/dist/index.d.ts +4 -1
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +4 -2
  25. package/dist/index.js.map +1 -1
  26. package/dist/legacy-pers-sdk.d.ts +79 -0
  27. package/dist/legacy-pers-sdk.d.ts.map +1 -0
  28. package/dist/managers/analytics-manager.d.ts +28 -0
  29. package/dist/managers/analytics-manager.d.ts.map +1 -0
  30. package/dist/managers/auth-manager.d.ts +80 -0
  31. package/dist/managers/auth-manager.d.ts.map +1 -0
  32. package/dist/managers/business-manager.d.ts +83 -0
  33. package/dist/managers/business-manager.d.ts.map +1 -0
  34. package/dist/managers/campaign-manager.d.ts +158 -0
  35. package/dist/managers/campaign-manager.d.ts.map +1 -0
  36. package/dist/managers/donation-manager.d.ts +27 -0
  37. package/dist/managers/donation-manager.d.ts.map +1 -0
  38. package/dist/managers/index.d.ts +18 -0
  39. package/dist/managers/index.d.ts.map +1 -0
  40. package/dist/managers/payment-manager.d.ts +44 -0
  41. package/dist/managers/payment-manager.d.ts.map +1 -0
  42. package/dist/managers/redemption-manager.d.ts +91 -0
  43. package/dist/managers/redemption-manager.d.ts.map +1 -0
  44. package/dist/managers/tenant-manager.d.ts +60 -0
  45. package/dist/managers/tenant-manager.d.ts.map +1 -0
  46. package/dist/managers/token-manager.d.ts +81 -0
  47. package/dist/managers/token-manager.d.ts.map +1 -0
  48. package/dist/managers/transaction-manager.d.ts +62 -0
  49. package/dist/managers/transaction-manager.d.ts.map +1 -0
  50. package/dist/managers/user-manager.d.ts +72 -0
  51. package/dist/managers/user-manager.d.ts.map +1 -0
  52. package/dist/package.json +6 -1
  53. package/dist/pers-sdk.d.ts +302 -13
  54. package/dist/pers-sdk.d.ts.map +1 -1
  55. package/dist/platform-adapters/angular-http-client.d.ts +35 -0
  56. package/dist/platform-adapters/angular-http-client.d.ts.map +1 -0
  57. package/dist/platform-adapters/browser-fetch-client.d.ts +30 -0
  58. package/dist/platform-adapters/browser-fetch-client.d.ts.map +1 -0
  59. package/dist/platform-adapters/index.d.ts +11 -0
  60. package/dist/platform-adapters/index.d.ts.map +1 -0
  61. package/dist/platform-adapters/node-http-client.d.ts +30 -0
  62. package/dist/platform-adapters/node-http-client.d.ts.map +1 -0
  63. package/dist/platform-adapters.cjs +201 -0
  64. package/dist/platform-adapters.cjs.map +1 -0
  65. package/dist/platform-adapters.js +197 -0
  66. package/dist/platform-adapters.js.map +1 -0
  67. package/dist/token.cjs +6 -5
  68. package/dist/token.cjs.map +1 -1
  69. package/dist/token.js +2 -1
  70. package/dist/token.js.map +1 -1
  71. package/package.json +6 -1
  72. package/dist/chunks/base-token-service-BA81_Ouq.js.map +0 -1
  73. package/dist/chunks/base-token-service-BQ6uFoki.cjs.map +0 -1
  74. package/dist/chunks/pers-sdk-DiwCwBiC.cjs.map +0 -1
  75. package/dist/chunks/pers-sdk-Rc8YKyNc.js.map +0 -1
package/README.md CHANGED
@@ -5,6 +5,15 @@
5
5
 
6
6
  **Platform-agnostic TypeScript SDK for PERS (Phygital Experience Rewards System)** - Core SDK providing domain-driven business logic and API integration for tourism loyalty applications.
7
7
 
8
+ ## 🚀 What's New in v1.3+
9
+
10
+ **✨ Enhanced Manager Pattern Architecture**
11
+ - **High-level domain managers** for intuitive API access
12
+ - **Platform adapters** for seamless integration
13
+ - **Clean separation** between managers and underlying SDKs
14
+ - **Improved TypeScript support** with better type inference
15
+ - **Backward compatibility** maintained for existing integrations
16
+
8
17
  ## PERS Ecosystem
9
18
 
10
19
  PERS is a comprehensive tourism loyalty platform bridging physical and digital experiences through loyalty programs, campaign management, payments, blockchain integration, business management, and analytics.
@@ -21,144 +30,409 @@ npm install @explorins/pers-sdk
21
30
  - **[@explorins/pers-sdk-react-native](https://www.npmjs.com/package/@explorins/pers-sdk-react-native)** - React Native providers and hooks
22
31
  - **Direct Integration** - Node.js, Vanilla JS, or custom frameworks
23
32
 
33
+ ## 🏗️ Architecture Overview
34
+
35
+ ```typescript
36
+ PersSDK
37
+ ├── Domain Managers (High-level) // Recommended for common operations
38
+ │ ├── auth: AuthManager
39
+ │ ├── users: UserManager
40
+ │ ├── tokens: TokenManager
41
+ │ ├── businesses: BusinessManager
42
+ │ ├── campaigns: CampaignManager
43
+ │ ├── redemptions: RedemptionManager
44
+ │ ├── transactions: TransactionManager
45
+ │ ├── payments: PaymentManager
46
+ │ └── analytics: AnalyticsManager
47
+ ├── Domain SDKs (Advanced) // Full feature access
48
+ │ ├── createBusinessSDK()
49
+ │ ├── createCampaignSDK()
50
+ │ └── TokenSDK, etc.
51
+ └── Core API Client // Direct API access
52
+ └── api(): PersApiClient
53
+ ```
54
+
24
55
  ## Quick Start
25
56
 
26
- ### Basic Setup
57
+ ### 1. Choose Your Integration Method
27
58
 
28
- ```typescript
29
- import { PersApiClient } from '@explorins/pers-sdk/core';
59
+ #### 🎯 **Recommended: Manager Pattern (High-level)**
30
60
 
31
- // Custom HTTP client (platform-specific)
32
- const httpClient = {
33
- get: async (url: string) => fetch(url).then(r => r.json()),
34
- post: async (url: string, data: any) =>
35
- fetch(url, { method: 'POST', body: JSON.stringify(data) }).then(r => r.json()),
36
- put: async (url: string, data: any) =>
37
- fetch(url, { method: 'PUT', body: JSON.stringify(data) }).then(r => r.json()),
38
- delete: async (url: string) =>
39
- fetch(url, { method: 'DELETE' }).then(r => r.json())
40
- };
61
+ ```typescript
62
+ import { PersSDK } from '@explorins/pers-sdk';
63
+ import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
41
64
 
42
- // Create API client
43
- const apiClient = new PersApiClient(httpClient, {
65
+ const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
44
66
  environment: 'production',
45
- apiVersion: 'v2',
46
67
  apiProjectKey: 'your-project-key'
47
68
  });
48
69
 
49
- // Login with external JWT (Firebase, Auth0, etc.)
50
- const result = await apiClient.loginUser(firebaseJWT);
70
+ // Clean, intuitive manager interface
71
+ const user = await sdk.auth.getCurrentUser();
72
+ const campaigns = await sdk.campaigns.getActiveCampaigns();
73
+ const tokens = await sdk.tokens.getTokens();
51
74
  ```
52
75
 
53
- ### Platform Examples
54
-
55
- #### Angular
76
+ #### ⚙️ **Advanced: Direct SDK Access**
56
77
 
57
78
  ```typescript
58
- import { PERS_ANGULAR_SDK_SERVICE } from '@explorins/pers-sdk-angular';
79
+ import { createBusinessSDK, createCampaignSDK } from '@explorins/pers-sdk';
80
+ import { PersApiClient } from '@explorins/pers-sdk/core';
81
+
82
+ const apiClient = new PersApiClient(httpClient, config);
83
+ const businessSDK = createBusinessSDK(apiClient);
84
+ const campaignSDK = createCampaignSDK(apiClient);
85
+ ```
86
+
87
+ ### 2. Platform-Specific Setup
88
+
89
+ #### Angular Integration
59
90
 
60
- @Injectable()
61
- export class AuthService {
62
- private persSDK = inject(PERS_ANGULAR_SDK_SERVICE);
91
+ ```typescript
92
+ // app.config.ts
93
+ import { provideHttpClient } from '@angular/common/http';
94
+ import { PersSDKService } from 'your-app/services/pers-sdk.service';
95
+
96
+ export const appConfig = {
97
+ providers: [
98
+ provideHttpClient(),
99
+ PersSDKService
100
+ ]
101
+ };
63
102
 
64
- async login(firebaseToken: string) {
65
- return this.persSDK.api().loginUser(firebaseToken);
103
+ // pers-sdk.service.ts
104
+ import { Injectable } from '@angular/core';
105
+ import { HttpClient } from '@angular/common/http';
106
+ import { PersSDK } from '@explorins/pers-sdk';
107
+ import { AngularHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
108
+
109
+ @Injectable({ providedIn: 'root' })
110
+ export class PersSDKService extends PersSDK {
111
+ constructor(httpClient: HttpClient) {
112
+ super(new AngularHttpClientAdapter(httpClient), {
113
+ environment: 'production',
114
+ apiProjectKey: 'your-project-key'
115
+ });
66
116
  }
67
117
  }
68
118
  ```
69
119
 
70
- #### React Native
120
+ #### React/Browser Setup
71
121
 
72
- ```tsx
73
- import { usePersSDK } from '@explorins/pers-sdk-react-native';
122
+ ```typescript
123
+ import { PersSDK } from '@explorins/pers-sdk';
124
+ import { BrowserFetchClientAdapter } from '@explorins/pers-sdk/platform-adapters';
74
125
 
75
- function LoginScreen() {
76
- const { login } = usePersSDK();
77
-
78
- const handleLogin = async () => {
79
- await login(firebaseToken);
80
- };
126
+ const sdk = new PersSDK(new BrowserFetchClientAdapter(), {
127
+ environment: 'production',
128
+ apiProjectKey: 'your-project-key'
129
+ });
130
+
131
+ // React Hook example
132
+ export function usePersSDK() {
133
+ return sdk;
81
134
  }
82
135
  ```
83
136
 
84
- ## Domain Architecture
137
+ #### Node.js Setup
85
138
 
86
139
  ```typescript
87
- // Domain-specific imports (recommended)
88
- import { PersApiClient } from '@explorins/pers-sdk/core';
89
- import { TokenSDK } from '@explorins/pers-sdk/token';
90
- import { createBusinessSDK } from '@explorins/pers-sdk/business';
91
- import { createCampaignSDK } from '@explorins/pers-sdk/campaign';
140
+ import { PersSDK } from '@explorins/pers-sdk';
141
+ import { NodeHttpClientAdapter } from '@explorins/pers-sdk/platform-adapters';
142
+
143
+ const sdk = new PersSDK(new NodeHttpClientAdapter(), {
144
+ environment: 'production',
145
+ apiProjectKey: 'your-project-key'
146
+ });
92
147
  ```
93
148
 
94
- ## Core Authentication
149
+ ## 📋 Domain Managers API Reference
150
+
151
+ ### 🔐 Authentication Manager
95
152
 
96
153
  ```typescript
97
- // Login with external JWT
98
- const authResult = await apiClient.loginUser(externalJWT);
154
+ // Login with external JWT (Firebase, Auth0, etc.)
155
+ const authResult = await sdk.auth.loginWithToken(jwtToken, 'user');
156
+ const adminResult = await sdk.auth.loginAdmin(adminJWT);
99
157
 
100
158
  // Check authentication status
101
- if (apiClient.hasValidAuth()) {
102
- console.log('User is authenticated');
103
- }
159
+ const isAuthenticated = await sdk.auth.isAuthenticated();
160
+ const hasValidAuth = sdk.auth.hasValidAuth();
104
161
 
105
- // Automatic token refresh handled internally
106
- await apiClient.refreshToken();
162
+ // User management
163
+ const currentUser = await sdk.auth.getCurrentUser();
107
164
 
108
- // Clear authentication
109
- await apiClient.clearAuth();
165
+ // Token management
166
+ const newTokens = await sdk.auth.refreshTokens();
167
+ await sdk.auth.clearAuth();
110
168
  ```
111
169
 
112
- ## Business Domain Examples
170
+ ### 👤 User Manager
113
171
 
114
- ### Token Management
115
172
  ```typescript
116
- import { TokenSDK } from '@explorins/pers-sdk/token';
173
+ // Current user operations
174
+ const user = await sdk.users.getCurrentUser();
175
+ await sdk.users.updateCurrentUser(userData);
176
+
177
+ // User lookup
178
+ const userById = await sdk.users.getUserById(identifier);
179
+ const publicProfiles = await sdk.users.getAllUsersPublic();
180
+
181
+ // Admin operations
182
+ const allUsers = await sdk.users.getAllUsers();
183
+ await sdk.users.updateUser(userId, userData);
184
+ await sdk.users.toggleUserStatus(user);
185
+ ```
117
186
 
118
- const tokenSDK = new TokenSDK(apiClient);
119
- const balances = await tokenSDK.getBalances(userId);
187
+ ### 🪙 Token Manager
188
+
189
+ ```typescript
190
+ // Token operations
191
+ const tokens = await sdk.tokens.getTokens();
192
+ const creditToken = await sdk.tokens.getActiveCreditToken();
193
+ const rewardTokens = await sdk.tokens.getRewardTokens();
194
+
195
+ // Balance operations
196
+ const balances = await sdk.tokens.getBalances(userId);
197
+ await sdk.tokens.transferTokens(transferData);
120
198
  ```
121
199
 
122
- ### Business Operations
200
+ ### 🏢 Business Manager
201
+
123
202
  ```typescript
124
- import { createBusinessSDK } from '@explorins/pers-sdk/business';
203
+ // Public business operations
204
+ const businesses = await sdk.businesses.getActiveBusinesses();
205
+ const business = await sdk.businesses.getBusinessById(id);
206
+ const types = await sdk.businesses.getBusinessTypes();
207
+
208
+ // Admin operations
209
+ const allBusinesses = await sdk.businesses.getAllBusinesses();
210
+ await sdk.businesses.createBusiness(businessData);
211
+ await sdk.businesses.updateBusiness(id, businessData);
212
+ ```
125
213
 
126
- const businessSDK = createBusinessSDK(apiClient);
127
- const businesses = await businessSDK.listBusinesses();
214
+ ### 🎯 Campaign Manager
215
+
216
+ ```typescript
217
+ // Public campaign operations
218
+ const campaigns = await sdk.campaigns.getActiveCampaigns();
219
+ const campaign = await sdk.campaigns.getCampaignById(id);
220
+
221
+ // User operations
222
+ await sdk.campaigns.claimCampaign(claimData);
223
+ const userClaims = await sdk.campaigns.getUserClaims();
224
+
225
+ // Admin operations
226
+ const allCampaigns = await sdk.campaigns.getAllCampaigns();
227
+ await sdk.campaigns.createCampaign(campaignData);
228
+ await sdk.campaigns.toggleCampaignStatus(campaignId);
229
+
230
+ // Advanced operations
231
+ const triggers = await sdk.campaigns.getCampaignTriggers();
232
+ await sdk.campaigns.setCampaignTrigger(campaignId, triggerId);
233
+ ```
234
+
235
+ ### 🎁 Redemption Manager
236
+
237
+ ```typescript
238
+ // Public redemption operations
239
+ const redemptions = await sdk.redemptions.getActiveRedemptions();
240
+ const types = await sdk.redemptions.getRedemptionTypes();
241
+
242
+ // User operations
243
+ await sdk.redemptions.redeemOffer(redemptionId);
244
+ const userRedemptions = await sdk.redemptions.getUserRedemptions();
245
+
246
+ // Admin operations
247
+ const allRedemptions = await sdk.redemptions.getAllRedemptions();
248
+ await sdk.redemptions.createRedemption(redemptionData);
249
+ await sdk.redemptions.toggleRedemptionStatus(redemptionId);
128
250
  ```
129
251
 
130
- ### Campaign Management
252
+ ### 💳 Payment Manager
253
+
131
254
  ```typescript
132
- import { createCampaignSDK } from '@explorins/pers-sdk/campaign';
255
+ // Payment operations
256
+ const intent = await sdk.payments.createPaymentIntent(100, 'usd', 'email', 'desc');
257
+ const tokens = await sdk.payments.getActivePurchaseTokens();
258
+ const purchases = await sdk.payments.getAllUserPurchases();
259
+ ```
133
260
 
134
- const campaignSDK = createCampaignSDK(apiClient);
135
- const campaigns = await campaignSDK.getActiveCampaigns();
261
+ ### 📊 Transaction Manager
262
+
263
+ ```typescript
264
+ // Transaction operations
265
+ const transaction = await sdk.transactions.getTransactionById(id);
266
+ await sdk.transactions.createTransaction(transactionData);
267
+ const history = await sdk.transactions.getUserTransactionHistory('all');
136
268
  ```
137
269
 
138
- ## Available Domains
270
+ ### 🏢 Tenant Manager
271
+
272
+ ```typescript
273
+ // Tenant configuration
274
+ const tenantInfo = await sdk.tenants.getTenantInfo();
275
+ const clientConfig = await sdk.tenants.getClientConfig();
276
+ const loginToken = await sdk.tenants.getLoginToken();
277
+
278
+ // Admin operations
279
+ await sdk.tenants.updateTenant(tenantData);
280
+ const admins = await sdk.tenants.getAdmins();
281
+ await sdk.tenants.createAdmin(adminData);
282
+ ```
283
+
284
+ ### 📈 Analytics Manager
285
+
286
+ ```typescript
287
+ // Transaction analytics
288
+ const analytics = await sdk.analytics.getTransactionAnalytics({
289
+ startDate: '2024-01-01',
290
+ endDate: '2024-12-31',
291
+ groupBy: 'month'
292
+ });
293
+ ```
139
294
 
295
+ ### 💝 Donations Manager
296
+
297
+ ```typescript
298
+ // Donation types management
299
+ const donationTypes = await sdk.donations.getDonationTypes();
300
+ ```
301
+
302
+ ## 🔧 Advanced Usage
303
+
304
+ ### Custom HTTP Client
305
+
306
+ ```typescript
307
+ import { HttpClient, RequestOptions } from '@explorins/pers-sdk/core';
308
+
309
+ class CustomHttpClient implements HttpClient {
310
+ async get<T>(url: string, options?: RequestOptions): Promise<T> {
311
+ // Your custom implementation
312
+ }
313
+
314
+ async post<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T> {
315
+ // Your custom implementation
316
+ }
317
+
318
+ async put<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T> {
319
+ // Your custom implementation
320
+ }
321
+
322
+ async delete<T>(url: string, options?: RequestOptions): Promise<T> {
323
+ // Your custom implementation
324
+ }
325
+ }
326
+
327
+ const sdk = new PersSDK(new CustomHttpClient(), config);
328
+ ```
329
+
330
+ ### Direct API Access
331
+
332
+ ```typescript
333
+ // For operations not covered by managers
334
+ const apiClient = sdk.api();
335
+
336
+ // Custom endpoints
337
+ const customData = await apiClient.get<CustomType>('/custom-endpoint');
338
+ await apiClient.post('/custom-endpoint', customData);
339
+
340
+ // Advanced auth operations
341
+ const isExpired = await apiClient.isTokenExpired(120);
342
+ const allExpired = await apiClient.areAllTokensExpired();
343
+ ```
344
+
345
+ ### Error Handling
346
+
347
+ ```typescript
348
+ import { PersApiError } from '@explorins/pers-sdk/core';
349
+
350
+ try {
351
+ const user = await sdk.auth.getCurrentUser();
352
+ } catch (error) {
353
+ if (error instanceof PersApiError) {
354
+ console.error('PERS API Error:', error.message, error.statusCode);
355
+ } else {
356
+ console.error('Unknown error:', error);
357
+ }
358
+ }
359
+ ```
360
+
361
+ ## 📦 Available Modules
362
+
363
+ ### Core Modules
140
364
  - `/core` - Core API client and authentication
141
- - `/token` - Token balances and transfers
365
+ - `/platform-adapters` - Ready-to-use HTTP client adapters
366
+
367
+ ### Domain Modules
142
368
  - `/business` - Business operations and management
143
- - `/campaign` - Marketing campaigns and challenges
144
- - `/transaction` - Payment and transaction history
369
+ - `/campaign` - Marketing campaigns and challenges
145
370
  - `/redemption` - Reward redemption system
371
+ - `/token` - Token balances and transfers
372
+ - `/transaction` - Payment and transaction history
146
373
  - `/payment` - Payment processing
147
374
  - `/user` - User profile management
148
- - `/web3` - Blockchain and wallet integration
149
375
  - `/analytics` - Reporting and analytics
150
376
  - `/tenant` - Multi-tenant management
377
+ - `/donation` - Donation management
378
+ - `/web3` - Blockchain and wallet integration
379
+ - `/web3-chain` - Web3 chain operations
380
+
381
+ ## ⚙️ Configuration
382
+
383
+ ```typescript
384
+ interface PersConfig {
385
+ environment: 'development' | 'staging' | 'production';
386
+ apiVersion?: 'v1' | 'v1.8' | 'v1.9' | 'v2';
387
+ apiProjectKey: string;
388
+ timeout?: number; // Request timeout (default: 30s)
389
+ retries?: number; // Retry attempts (default: 3)
390
+ authProvider?: PersAuthProvider; // Custom auth provider
391
+ }
392
+ ```
393
+
394
+ ## 🔄 Migration Guide
151
395
 
152
- ## Configuration
396
+ ### From Legacy SDK to Manager Pattern
153
397
 
398
+ **Before (Legacy):**
154
399
  ```typescript
155
- const config = {
156
- environment: 'production', // 'development' | 'staging' | 'production'
157
- apiVersion: 'v2', // 'v1' | 'v1.8' | 'v1.9' | 'v2'
158
- apiProjectKey: 'your-key', // Required: Your PERS project key
159
- timeout: 30000, // Request timeout (default: 30s)
160
- retries: 3 // Retry attempts (default: 3)
400
+ const businessSDK = createBusinessSDK(apiClient);
401
+ const businesses = await businessSDK.getActiveBusinesses();
402
+ ```
403
+
404
+ **After (Manager Pattern):**
405
+ ```typescript
406
+ const sdk = new PersSDK(httpClient, config);
407
+ const businesses = await sdk.businesses.getActiveBusinesses();
408
+ ```
409
+
410
+ **Benefits:**
411
+ - ✅ Cleaner API surface
412
+ - ✅ Better TypeScript inference
413
+ - ✅ Consistent error handling
414
+ - ✅ Easier testing and mocking
415
+ - ✅ Future-proof architecture
416
+
417
+ ## 📊 Bundle Size
418
+
419
+ - **Core SDK**: ~90 KB (minified)
420
+ - **Individual domains**: 2-20 KB each
421
+ - **Manager pattern**: Minimal overhead (~5 KB)
422
+ - **Tree-shaking friendly**: Import only what you need
423
+
424
+ ## 🧪 Testing
425
+
426
+ ```typescript
427
+ // Mock manager for testing
428
+ const mockUserManager = {
429
+ getCurrentUser: jest.fn().mockResolvedValue(mockUser),
430
+ updateCurrentUser: jest.fn().mockResolvedValue(updatedUser)
161
431
  };
432
+
433
+ const sdk = {
434
+ users: mockUserManager
435
+ } as jest.Mocked<PersSDK>;
162
436
  ```
163
437
 
164
438
  ## Dependencies
@@ -175,10 +449,6 @@ const config = {
175
449
  - [@explorins/pers-shared](https://www.npmjs.com/package/@explorins/pers-shared) - Shared types and DTOs
176
450
  - [@explorins/web3-ts](https://www.npmjs.com/package/@explorins/web3-ts) - Web3 utilities
177
451
 
178
- ## Documentation
179
-
180
- For comprehensive API documentation, usage guides, and examples, visit the [PERS SDK Documentation](https://docs.pers.ninja).
181
-
182
452
  ## License
183
453
 
184
454
  MIT License - see [LICENSE](LICENSE) file for details.
@@ -0,0 +1,139 @@
1
+ import { a as TokenApi, b as TokenService } from './token-sdk-BW4kkJb3.js';
2
+
3
+ /**
4
+ * Abstract Base Token Service - Explicit Initialization Pattern
5
+ *
6
+ * Platform-agnostic token operations with Promise-based API.
7
+ * Framework services extend this and control initialization lifecycle.
8
+ *
9
+ * Benefits:
10
+ * - Explicit initialization control
11
+ * - Better error boundaries
12
+ * - Clear lifecycle management
13
+ * - Testable initialization state
14
+ * - Zero framework dependencies
15
+ */
16
+ class BaseTokenService {
17
+ constructor() {
18
+ this._isInitialized = false;
19
+ }
20
+ // ==========================================
21
+ // INITIALIZATION LIFECYCLE
22
+ // ==========================================
23
+ /**
24
+ * LIFECYCLE: Initialize token service with API client
25
+ * Must be called before using any token operations
26
+ */
27
+ initializeTokenService(apiClient) {
28
+ if (!apiClient) {
29
+ throw new Error('Cannot initialize TokenService: apiClient is null or undefined');
30
+ }
31
+ if (!this._isInitialized) {
32
+ this._tokenApi = new TokenApi(apiClient);
33
+ this._tokenBusinessService = new TokenService(this._tokenApi);
34
+ this._isInitialized = true;
35
+ }
36
+ }
37
+ /**
38
+ * LIFECYCLE: Check if token service is initialized
39
+ */
40
+ get isTokenServiceInitialized() {
41
+ return this._isInitialized;
42
+ }
43
+ /**
44
+ * INTERNAL: Get token business service (throws if not initialized)
45
+ */
46
+ get tokenBusinessService() {
47
+ if (!this._tokenBusinessService) {
48
+ throw new Error('TokenService not initialized. Call initializeTokenService(apiClient) first.');
49
+ }
50
+ return this._tokenBusinessService;
51
+ }
52
+ // ==========================================
53
+ // PUBLIC OPERATIONS
54
+ // ==========================================
55
+ /**
56
+ * PUBLIC: Get all remote tokens
57
+ */
58
+ getRemoteTokens() {
59
+ return this.tokenBusinessService.getRemoteTokens();
60
+ }
61
+ /**
62
+ * PUBLIC: Get all remote token types
63
+ */
64
+ getRemoteTokenTypes() {
65
+ return this.tokenBusinessService.getRemoteTokenTypes();
66
+ }
67
+ /**
68
+ * PUBLIC: Get active credit token
69
+ */
70
+ getRemoteActiveCreditToken() {
71
+ return this.tokenBusinessService.getRemoteActiveCreditToken();
72
+ }
73
+ /**
74
+ * PUBLIC: Get reward tokens
75
+ */
76
+ getRemoteRewardTokens() {
77
+ return this.tokenBusinessService.getRemoteRewardTokens();
78
+ }
79
+ /**
80
+ * PUBLIC: Get status tokens
81
+ */
82
+ getRemoteStatusTokens() {
83
+ return this.tokenBusinessService.getRemoteStatusTokens();
84
+ }
85
+ /**
86
+ * PUBLIC: Get token by contract address
87
+ */
88
+ getTokenByContractAddress(contractAddress, contractTokenId) {
89
+ return this.tokenBusinessService.getTokenByContractAddress(contractAddress, contractTokenId);
90
+ }
91
+ // ==========================================
92
+ // ADMIN OPERATIONS
93
+ // ==========================================
94
+ /**
95
+ * ADMIN: Create token metadata
96
+ */
97
+ createTokenMetadata(tokenId, tokenData) {
98
+ return this.tokenBusinessService.createTokenMetadata(tokenId, tokenData);
99
+ }
100
+ /**
101
+ * ADMIN: Toggle token active status
102
+ */
103
+ toggleTokenActive(tokenId) {
104
+ return this.tokenBusinessService.toggleTokenActive(tokenId);
105
+ }
106
+ /**
107
+ * ADMIN: Create new token
108
+ */
109
+ createToken(tokenData) {
110
+ return this.tokenBusinessService.createToken(tokenData);
111
+ }
112
+ /**
113
+ * ADMIN: Update token
114
+ */
115
+ updateToken(tokenId, tokenData) {
116
+ return this.tokenBusinessService.updateToken(tokenId, tokenData);
117
+ }
118
+ /**
119
+ * ADMIN: Set mainnet contract address
120
+ */
121
+ setMainnetContract(tokenId, contractAddress, chainId) {
122
+ return this.tokenBusinessService.setMainnetContract(tokenId, contractAddress, chainId);
123
+ }
124
+ /**
125
+ * ADMIN: Toggle token metadata status
126
+ */
127
+ toggleTokenMetadataStatus(metadataId) {
128
+ return this.tokenBusinessService.toggleTokenMetadataStatus(metadataId);
129
+ }
130
+ /**
131
+ * ADMIN: Create token type
132
+ */
133
+ createTokenType(tokenType) {
134
+ return this.tokenBusinessService.createTokenType(tokenType);
135
+ }
136
+ }
137
+
138
+ export { BaseTokenService as B };
139
+ //# sourceMappingURL=base-token-service-D0KANDgM.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"base-token-service-D0KANDgM.js","sources":["../../src/token/base/base-token-service.ts"],"sourcesContent":[null],"names":["TokenBusinessService"],"mappings":"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"}