@explorins/pers-sdk 1.1.0-beta.0 → 1.1.2

package/src/user/services/user-service.ts

@@ -0,0 +1,75 @@
+import { UserDTO, UserCreateRequestDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+import { UserApi } from '../api/user-api';
+import { UserPublicProfileDTO } from '../models';
+
+/**
+ * Platform-Agnostic User Service
+ * 
+ * Contains user business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework UserApiService capabilities exactly.
+ */
+export class UserService {
+  constructor(private userApi: UserApi) {}
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get all users public profiles with optional filtering
+   * ✅ FIXED: Uses framework-compatible inline filter type
+   */
+  async getAllUsersPublicProfiles(filter: {key: string, value: string} | null = null): Promise<UserPublicProfileDTO[]> {
+    return this.userApi.getAllUsersPublicProfiles(filter);
+  }
+
+  // ==========================================
+  // AUTHENTICATED OPERATIONS
+  // ==========================================
+
+  /**
+   * AUTH: Get current authenticated user
+   */
+  async getRemoteUser(): Promise<UserDTO> {
+    return this.userApi.getRemoteUser();
+  }
+
+  /**
+   * AUTH: Update current authenticated user
+   */
+  async updateRemoteUser(updateRequest: UserCreateRequestDTO): Promise<UserDTO> {
+    return this.userApi.updateRemoteUser(updateRequest);
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Get all remote users
+   * ✅ FIXED: Matches API method signature (no parameters needed)
+   */
+  async getAllRemoteUsers(): Promise<UserDTO[]> {
+    return this.userApi.getAllRemoteUsers();
+  }
+
+  /**
+   * ADMIN: Update user as admin
+   */
+  async updateUserAsAdmin(id: string, userData: UserCreateRequestDTO): Promise<UserDTO> {
+    return this.userApi.updateUserAsAdmin(id, userData);
+  }
+
+  async getUserByUniqueIdentifier(id: string): Promise<UserDTO> {
+    return this.userApi.getUserByUniqueIdentifier(id);
+  }
+
+  /**
+   * ADMIN: Toggle user active status by user object
+   * ✅ FIXED: Matches API method signature exactly
+   */
+  async toggleUserActiveStatusByUser(user: UserDTO): Promise<UserDTO> {
+    return this.userApi.toggleUserActiveStatusByUser(user);
+  }
+}

package/src/user-status/api/user-status-api.ts

@@ -0,0 +1,78 @@
+import { PersApiClient } from '../../core/pers-api-client';
+import { UserStatusTypeDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Platform-Agnostic User Status API Client
+ * 
+ * Handles user status operations using the PERS backend.
+ * Matches framework UserStatusApiService methods exactly.
+ * 
+ * ✅ UPDATED: All endpoints updated to new RESTful /users patterns
+ * 
+ * Error handling patterns follow framework implementation:
+ * - getRemoteEarnedUserStatus() uses silent fallback (empty array)
+ * - Other operations throw errors for proper error handling
+ */
+export class UserStatusApi {
+  constructor(private apiClient: PersApiClient) {}
+
+  private readonly basePath = '/users';
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get remote user status types
+   * ✅ UPDATED: /user/status-type → /users/status-types
+   */
+  async getRemoteUserStatusTypes(): Promise<UserStatusTypeDTO[]> {
+    try {
+      return await this.apiClient.get<UserStatusTypeDTO[]>(`${this.basePath}/status-types`);
+    } catch (error) {
+      console.error('Error getting user status types', error);
+      throw error;
+    }
+  }
+
+  // ==========================================
+  // AUTHENTICATED OPERATIONS
+  // ==========================================
+
+  /**
+   * AUTH: Get earned user status for authenticated user
+   * ✅ UPDATED: /user/auth/status → /users/me/status
+   * ✅ FIXED: Returns UserStatusTypeDTO[] to match framework exactly
+   * Note: Uses silent fallback pattern from framework - returns empty array on error
+   */
+  async getRemoteEarnedUserStatus(): Promise<UserStatusTypeDTO[]> {
+    try {
+      return await this.apiClient.get<UserStatusTypeDTO[]>(`${this.basePath}/me/status`);
+    } catch (error) {
+      console.error('Error getting user status', error);
+      // ✅ FIXED: Silent fallback pattern from framework implementation
+      return [];
+    }
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Create user status type
+   * ✅ UPDATED: /user/admin/status-type → /users/status-types
+   */
+  async createUserStatusType(userStatusType: UserStatusTypeDTO): Promise<UserStatusTypeDTO> {
+    try {
+      return await this.apiClient.post<UserStatusTypeDTO>(`${this.basePath}/status-types`, userStatusType);
+    } catch (error) {
+      console.error('Error creating user status type', error);
+      throw error;
+    }
+  }
+
+  // ❌ REMOVED: Methods not present in framework
+  // - updateUserStatusType() - Framework doesn't have this operation
+  // - toggleUserStatusTypeActive() - Framework doesn't have this operation
+}

package/src/user-status/index.ts

@@ -0,0 +1,55 @@
+/**
+ * @explorins/pers-sdk-user-status
+ * 
+ * Platform-agnostic User Status Domain SDK for PERS ecosystem
+ * Handles user status management and type operations
+ */
+
+// API Layer
+export { UserStatusApi } from './api/user-status-api';
+
+// Service Layer  
+export { UserStatusService } from './services/user-status-service';
+
+// Models & Types - re-export all centralized interfaces
+export * from '../shared/interfaces/pers-shared-lib.interfaces';
+
+// Models & Types - imported from centralized interfaces
+
+// Factory function for creating user-status SDK instance
+import { PersApiClient } from '../core/pers-api-client';
+import { UserStatusApi } from './api/user-status-api';
+import { UserStatusService } from './services/user-status-service';
+import { UserStatusTypeDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Create a complete User Status SDK instance
+ * 
+ * @param apiClient - Configured PERS API client
+ * @returns User Status SDK with flattened structure for better DX
+ */
+export function createUserStatusSDK(apiClient: PersApiClient) {
+  const userStatusApi = new UserStatusApi(apiClient);
+  const userStatusService = new UserStatusService(userStatusApi);
+  
+  return {
+    // Direct access to service methods (primary interface)
+    // ✅ FRAMEWORK ALIGNED: Only methods actually used by framework
+    
+    // Public methods
+    getRemoteUserStatusTypes: () => userStatusService.getRemoteUserStatusTypes(),
+    
+    // Auth methods
+    getRemoteEarnedUserStatus: () => userStatusService.getRemoteEarnedUserStatus(),
+    
+    // Admin methods
+    createUserStatusType: (userStatusType: UserStatusTypeDTO) => 
+      userStatusService.createUserStatusType(userStatusType),
+    
+    // Advanced access for edge cases
+    api: userStatusApi,
+    service: userStatusService
+  };
+}
+
+export type UserStatusSDK = ReturnType<typeof createUserStatusSDK>;

package/src/user-status/models/index.ts

@@ -0,0 +1,11 @@
+/**
+ * User Status Domain Models
+ * 
+ * Re-exports from centralized pers-shared interfaces for consistency with backend
+ * and to provide a single import source for user-status-related types.
+ */
+
+// Core user status entities from centralized pers-shared interfaces
+export type {
+  UserStatusTypeDTO
+} from '../../shared/interfaces/pers-shared-lib.interfaces';

package/src/user-status/services/user-status-service.ts

@@ -0,0 +1,51 @@
+import { UserStatusApi } from '../api/user-status-api';
+import { UserStatusTypeDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Platform-Agnostic User Status Service
+ * 
+ * Contains user status business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework UserStatusApiService capabilities exactly.
+ */
+export class UserStatusService {
+  constructor(private userStatusApi: UserStatusApi) {}
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get remote user status types
+   */
+  async getRemoteUserStatusTypes(): Promise<UserStatusTypeDTO[]> {
+    return this.userStatusApi.getRemoteUserStatusTypes();
+  }
+
+  // ==========================================
+  // AUTHENTICATED OPERATIONS
+  // ==========================================
+
+  /**
+   * AUTH: Get earned user status for authenticated user
+   */
+  async getRemoteEarnedUserStatus(): Promise<UserStatusTypeDTO[]> {
+    return this.userStatusApi.getRemoteEarnedUserStatus();
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Create user status type
+   */
+  async createUserStatusType(userStatusType: UserStatusTypeDTO): Promise<UserStatusTypeDTO> {
+    return this.userStatusApi.createUserStatusType(userStatusType);
+  }
+
+  // ❌ REMOVED: Business logic methods not present in framework
+  // - hasUserReachedStatusLevel() - Framework doesn't need this logic
+  // - getUserHighestStatusLevel() - Framework doesn't need this logic
+  // These can be added later if actually needed
+}

package/src/web3/api/web3-api.ts

@@ -0,0 +1,68 @@
+import { Web3ChainService } from '../../web3-chain/services/web3-chain-service';
+import type { ContractAbi } from 'web3';
+import { 
+  getAddressTokenBalanceByContract,
+  getSmartContractInstance,
+  getTokenOfOwnerByIndex, 
+  getTokenUri
+} from '@explorins/web3-ts';
+
+
+export class Web3Api {
+  
+  constructor(
+    private web3ChainService: Web3ChainService,
+  ) {}
+
+  async getTokenBalance(request: {
+    accountAddress: string;
+    contractAddress: string;
+    abi: ContractAbi;
+    tokenId: string | null;
+    chainId: number;
+  }): Promise<number> {
+    const web3 = await this.web3ChainService.getWeb3ByChainId(request.chainId);
+
+    const tokenContract = getSmartContractInstance(request.contractAddress, request.abi, web3);
+    const balance = await getAddressTokenBalanceByContract(
+      tokenContract, 
+      request.accountAddress, 
+      request.tokenId
+    );
+    
+    return Number(balance);
+  }
+
+  async getTokenUri(request: {
+    contractAddress: string;
+    abi: ContractAbi;
+    tokenId: string;
+    chainId: number;
+  }): Promise<string> {
+    const web3 = await this.web3ChainService.getWeb3ByChainId(request.chainId);
+    
+    // ✅ DIRECT: Use web3-ts functions directly
+    const tokenContract = getSmartContractInstance(request.contractAddress, request.abi, web3);
+    const tokenId = Number(request.tokenId);
+    const tokenUri = await getTokenUri(tokenContract, tokenId);
+    
+    return String(tokenUri);
+  }
+
+
+  async getTokenOfOwnerByIndex(request: {
+    contractAddress: string;
+    abi: ContractAbi;
+    accountAddress: string;
+    tokenIndex: number;
+    chainId: number;
+  }): Promise<string> {
+    const web3 = await this.web3ChainService.getWeb3ByChainId(request.chainId);
+    
+    // ✅ DIRECT: Use web3-ts functions directly
+    const tokenContract = getSmartContractInstance(request.contractAddress, request.abi, web3);
+    const tokenId = await getTokenOfOwnerByIndex(tokenContract, request.accountAddress, request.tokenIndex);
+    
+    return String(tokenId);
+  }
+}

package/src/web3/index.ts

@@ -0,0 +1,38 @@
+import { PersApiClient } from '../core/pers-api-client';
+import { Web3Api } from './api/web3-api';
+import { Web3Service } from './services/web3-service';
+import { createWeb3ChainSDK } from '../web3-chain';
+import { ContractAbi, ERC1155CollectionRequest, ERC20BalanceRequest, ERC721CollectionRequest, ERC721CollectionResponse, Web3BalanceRequest, Web3BalanceResponse, Web3TokenListRequest, Web3TokenListResponse } from './models';
+import { Web3ProviderService } from '../web3-chain/services/provider.service';
+
+export function createWeb3SDK(
+  apiClient: PersApiClient,
+  web3ProviderService: Web3ProviderService,
+) {
+  const web3ChainSDK = createWeb3ChainSDK(apiClient, web3ProviderService);
+  
+  const web3Api = new Web3Api(
+    web3ChainSDK.service, 
+  );
+  
+  const web3Service = new Web3Service(web3Api, web3ChainSDK.service);
+  
+  return {
+
+    getCreditsBalance: (request: ERC20BalanceRequest): Promise<Web3BalanceResponse> => 
+      web3Service.getERC20Balance(request),
+    
+    getRewardsCollection: (request: ERC1155CollectionRequest): Promise<Web3TokenListResponse> => 
+      web3Service.getERC1155Collection(request),
+    
+    getStampsCollection: (request: ERC721CollectionRequest): Promise<ERC721CollectionResponse> => 
+      web3Service.getERC721Collection(request),
+    
+    api: web3Api,
+    service: web3Service
+  };
+}
+
+export * from './models';
+export type { ERC20BalanceRequest, ERC1155CollectionRequest, ERC721CollectionRequest, ERC721CollectionResponse, NFTItem } from './models';
+export * from '../shared/interfaces/pers-shared-lib.interfaces';

package/src/web3/models/index.ts

@@ -0,0 +1,150 @@
+import type { ContractAbi, Web3 } from 'web3';
+import type { TokenDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+// ✅ REMOVE: Custom Web3ContractAbi type (no longer needed)
+// export type Web3ContractAbi = readonly AbiFragment[] | AbiFragment[];
+
+export interface Web3BalanceRequest {
+  accountAddress: string;
+  token: TokenDTO;
+  tokenId: string | null;
+}
+
+export interface Web3BalanceResponse {
+  rawBalance: number;
+  formattedBalance: string;
+  decimals: number;
+  symbol: string;
+  hasBalance: boolean;
+}
+
+export interface Web3TokenConfig {
+  token: TokenDTO;
+  tokenIds?: (string | null)[];
+  metadata?: any[];
+}
+
+export interface Web3TokenListRequest {
+  accountAddress: string;
+  tokens: Web3TokenConfig[];
+}
+
+export interface Web3TokenResult {
+  tokenId: string | null;
+  balance: number;
+  formattedBalance: string;
+  hasBalance: boolean;
+  metadata: any | null;
+}
+
+export interface Web3TokenListResponse {
+  accountAddress: string;
+  tokens: {
+    token: TokenDTO;
+    results: Web3TokenResult[];
+  }[];
+}
+
+export interface NFTItem {
+  tokenId: string;
+  name: string;
+  description: string;
+  imageUrl: string;
+  rawBalance: number;
+  formattedBalance: string;
+  hasBalance: boolean;
+  metadata: any;
+  tokenIndex: number;
+}
+
+export interface ERC721CollectionRequest {
+  accountAddress: string;
+  nftContracts: TokenDTO[];
+  maxNFTsPerContract?: number;
+}
+
+export interface ERC721CollectionResponse {
+  accountAddress: string;
+  contracts: {
+    token: TokenDTO;
+    totalNFTs: number;
+    nfts: NFTItem[];
+    hasMore: boolean;
+  }[];
+  summary: {
+    totalContracts: number;
+    totalNFTs: number;
+    loadingTime: number;
+  };
+}
+
+// ✅ NEW: ERC20 Balance types (simplified)
+export interface ERC20BalanceRequest {
+  accountAddress: string;
+  token: TokenDTO;
+}
+
+// ✅ NEW: ERC1155 Collection types (clearer naming)
+export interface ERC1155CollectionRequest {
+  accountAddress: string;
+  tokens: TokenDTO[];
+}
+
+// ✅ RE-EXPORT: Standard Web3.js types for consumers
+export type { ContractAbi } from 'web3';
+
+// ✅ CACHE: Simple cache interface with TTL
+export interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+  ttl: number;
+}
+
+export interface CacheStorage {
+  [key: string]: CacheEntry<unknown>;
+}
+
+export class SimpleCache {
+  private storage: CacheStorage = {};
+  private readonly defaultTTL = 10 * 1000; // 10 seconds
+
+  set<T>(key: string, data: T, ttl?: number): void {
+    this.storage[key] = {
+      data,
+      timestamp: Date.now(),
+      ttl: ttl ?? this.defaultTTL
+    };
+  }
+
+  get<T>(key: string): T | null {
+    const entry = this.storage[key];
+    
+    if (!entry) {
+      return null;
+    }
+
+    const now = Date.now();
+    const isExpired = (now - entry.timestamp) > entry.ttl;
+
+    if (isExpired) {
+      delete this.storage[key];
+      return null;
+    }
+
+    return entry.data as T;
+  }
+
+  clear(): void {
+    this.storage = {};
+  }
+
+  cleanup(): void {
+    const now = Date.now();
+    Object.keys(this.storage).forEach(key => {
+      const entry = this.storage[key];
+      if ((now - entry.timestamp) > entry.ttl) {
+        delete this.storage[key];
+      }
+    });
+  }
+}