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

package/src/token/base/base-token-service.ts

@@ -0,0 +1,167 @@
+import { PersApiClient } from '../../core/pers-api-client';
+import { TokenApi } from '../api/token-api';
+import { TokenService as TokenBusinessService } from '../services/token-service';
+import { 
+  TokenDTO,
+  TokenStorageData,
+  TokenCreateRequestDTO,
+  TokenUpdateRequestDTO,
+  TokenMetadataDTO
+} from '../models';
+import { TokenTypeDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Abstract Base Token Service - Explicit Initialization Pattern
+ * 
+ * Platform-agnostic token operations with Promise-based API.
+ * Framework services extend this and control initialization lifecycle.
+ * 
+ * Benefits:
+ * - Explicit initialization control
+ * - Better error boundaries  
+ * - Clear lifecycle management
+ * - Testable initialization state
+ * - Zero framework dependencies
+ */
+export abstract class BaseTokenService {
+  // Private token service layers - initialized explicitly
+  private _tokenApi?: TokenApi;
+  private _tokenBusinessService?: TokenBusinessService;
+  private _isInitialized = false;
+
+  // ==========================================
+  // INITIALIZATION LIFECYCLE
+  // ==========================================
+
+  /**
+   * LIFECYCLE: Initialize token service with API client
+   * Must be called before using any token operations
+   */
+  protected initializeTokenService(apiClient: PersApiClient): void {
+    if (!apiClient) {
+      throw new Error('Cannot initialize TokenService: apiClient is null or undefined');
+    }
+
+    if (!this._isInitialized) {
+      this._tokenApi = new TokenApi(apiClient);
+      this._tokenBusinessService = new TokenBusinessService(this._tokenApi);
+      this._isInitialized = true;
+    }
+  }
+
+  /**
+   * LIFECYCLE: Check if token service is initialized
+   */
+  protected get isTokenServiceInitialized(): boolean {
+    return this._isInitialized;
+  }
+
+  /**
+   * INTERNAL: Get token business service (throws if not initialized)
+   */
+  private get tokenBusinessService(): TokenBusinessService {
+    if (!this._tokenBusinessService) {
+      throw new Error('TokenService not initialized. Call initializeTokenService(apiClient) first.');
+    }
+    return this._tokenBusinessService;
+  }
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get all remote tokens
+   */
+  public getRemoteTokens(): Promise<TokenDTO[]> {
+    return this.tokenBusinessService.getRemoteTokens();
+  }
+
+  /**
+   * PUBLIC: Get all remote token types
+   */
+  public getRemoteTokenTypes(): Promise<TokenTypeDTO[]> {
+    return this.tokenBusinessService.getRemoteTokenTypes();
+  }
+
+  /**
+   * PUBLIC: Get active credit token
+   */
+  public getRemoteActiveCreditToken(): Promise<TokenDTO> {
+    return this.tokenBusinessService.getRemoteActiveCreditToken();
+  }
+
+  /**
+   * PUBLIC: Get reward tokens
+   */
+  public getRemoteRewardTokens(): Promise<TokenDTO[]> {
+    return this.tokenBusinessService.getRemoteRewardTokens();
+  }
+
+  /**
+   * PUBLIC: Get status tokens
+   */
+  public getRemoteStatusTokens(): Promise<TokenDTO[]> {
+    return this.tokenBusinessService.getRemoteStatusTokens();
+  }
+
+  /**
+   * PUBLIC: Get token by contract address
+   */
+  public getTokenByContractAddress(contractAddress: string, contractTokenId: string | null): Promise<TokenDTO> {
+    return this.tokenBusinessService.getTokenByContractAddress(contractAddress, contractTokenId);
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Create token metadata
+   */
+  public createTokenMetadata(tokenId: string, tokenData: TokenStorageData): Promise<TokenDTO> {
+    return this.tokenBusinessService.createTokenMetadata(tokenId, tokenData);
+  }
+
+  /**
+   * ADMIN: Toggle token active status
+   */
+  public toggleTokenActive(tokenId: string): Promise<TokenDTO> {
+    return this.tokenBusinessService.toggleTokenActive(tokenId);
+  }
+
+  /**
+   * ADMIN: Create new token
+   */
+  public createToken(tokenData: TokenCreateRequestDTO): Promise<TokenDTO> {
+    return this.tokenBusinessService.createToken(tokenData);
+  }
+
+  /**
+   * ADMIN: Update token
+   */
+  public updateToken(tokenId: string, tokenData: TokenUpdateRequestDTO): Promise<TokenDTO> {
+    return this.tokenBusinessService.updateToken(tokenId, tokenData);
+  }
+
+  /**
+   * ADMIN: Set mainnet contract address
+   */
+  public setMainnetContract(tokenId: string, contractAddress: string, chainId: number): Promise<TokenDTO> {
+    return this.tokenBusinessService.setMainnetContract(tokenId, contractAddress, chainId);
+  }
+
+  /**
+   * ADMIN: Toggle token metadata status
+   */
+  public toggleTokenMetadataStatus(metadataId: string): Promise<TokenMetadataDTO> {
+    return this.tokenBusinessService.toggleTokenMetadataStatus(metadataId);
+  }
+
+  /**
+   * ADMIN: Create token type
+   */
+  public createTokenType(tokenType: TokenTypeDTO): Promise<TokenTypeDTO> {
+    return this.tokenBusinessService.createTokenType(tokenType);
+  }
+}

package/src/token/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @explorins/pers-sdk-token
+ * 
+ * Platform-agnostic Token Domain SDK for PERS ecosystem
+ * Modern class-based approach for optimal performance and developer experience
+ */
+
+// 🚀 MAIN SDK EXPORT - Recommended approach
+export { TokenSDK } from './token-sdk';
+
+// 🔧 CORE COMPONENTS - For advanced usage
+export { TokenApi } from './api/token-api';
+export { TokenService } from './services/token-service';
+
+// 📋 MODELS & TYPES
+export * from './models';
+export * from '../shared/interfaces/pers-shared-lib.interfaces';
+
+// 🔄 LEGACY EXPORTS - For backward compatibility (deprecated)
+export { BaseTokenService } from './base/base-token-service';
+// Note: ConcreteTokenService has been replaced by TokenSDK class-based approach
+
+// ==========================================
+// INHERITANCE PATTERN - CLEAN ARCHITECTURE
+// ==========================================
+// Framework services extend TokenService directly:
+//
+// Example usage:
+//   export class TokenSdkApiService extends TokenService {
+//     private persSDK = inject(PERS_ANGULAR_SDK_SERVICE);
+//     protected get apiClient() { return this.persSDK.api(); }
+//   }
+//
+// Benefits:
+// - Zero boilerplate: Just extend and provide apiClient
+// - Type safety: Full IntelliSense support
+// - Platform agnostic: SDK stays pure Promise-based
+// - Framework flexibility: Add Observable wrappers as needed

package/src/token/models/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Token Domain Models
+ * 
+ * Re-exports from @explorins/pers-shared for consistency with backend
+ * and to provide a single import source for token-related types.
+ */
+
+// Core token entities from centralized pers-shared interfaces
+export type {
+  TokenDTO,
+  TokenTypeDTO,
+  TokenCreateRequestDTO,
+  TokenUpdateRequestDTO,
+  TokenMetadataDTO,
+  TokenStorageData
+} from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+// Local token interfaces
+export interface TokenMetadataAttribute {
+  trait_type: TokenMetadataAttributeType;
+  value: string;
+}
+
+export type TokenMetadataAttributeType = 'expiry_date' | 'creator_account_address' | 'preview_url' | 'creatorAccountAddress'
+
+export interface TokenAttribute {
+  trait_type: string;
+  value: string | number;
+  display_type?: string;
+}

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

@@ -0,0 +1,125 @@
+import { TokenApi } from '../api/token-api';
+import { 
+  TokenDTO,
+  TokenStorageData,
+  TokenCreateRequestDTO,
+  TokenUpdateRequestDTO,
+  TokenMetadataDTO
+} from '../models';
+import { TokenTypeDTO } from '../../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Platform-Agnostic Token Service
+ * 
+ * Contains token business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework TokenApiService capabilities exactly.
+ */
+export class TokenService {
+  constructor(private tokenApi: TokenApi) {}
+
+  // ==========================================
+  // PUBLIC OPERATIONS
+  // ==========================================
+
+  /**
+   * PUBLIC: Get all remote tokens
+   */
+  async getRemoteTokens(): Promise<TokenDTO[]> {
+    return this.tokenApi.getRemoteTokens();
+  }
+
+  /**
+   * PUBLIC: Get all remote token types
+   */
+  async getRemoteTokenTypes(): Promise<TokenTypeDTO[]> {
+    return this.tokenApi.getRemoteTokenTypes();
+  }
+
+  /**
+   * PUBLIC: Get active credit token
+   */
+  async getRemoteActiveCreditToken(): Promise<TokenDTO> {
+    return this.tokenApi.getRemoteActiveCreditToken();
+  }
+
+  /**
+   * PUBLIC: Get reward tokens
+   */
+  async getRemoteRewardTokens(): Promise<TokenDTO[]> {
+    return this.tokenApi.getRemoteRewardTokens();
+  }
+
+  /**
+   * PUBLIC: Get status tokens
+   */
+  async getRemoteStatusTokens(): Promise<TokenDTO[]> {
+    return this.tokenApi.getRemoteStatusTokens();
+  }
+
+  /**
+   * PUBLIC: Get token by contract address
+   * ✅ FIXED: Matches framework parameter types exactly
+   */
+  async getTokenByContractAddress(contractAddress: string, contractTokenId: string | null): Promise<TokenDTO> {
+    return this.tokenApi.getTokenByContractAddress(contractAddress, contractTokenId);
+  }
+
+  // ==========================================
+  // ADMIN OPERATIONS
+  // ==========================================
+
+  /**
+   * ADMIN: Create token metadata
+   */
+  async createTokenMetadata(tokenId: string, tokenData: TokenStorageData): Promise<TokenDTO> {
+    return this.tokenApi.createTokenMetadata(tokenId, tokenData);
+  }
+
+  /**
+   * ADMIN: Toggle token active status
+   */
+  async toggleTokenActive(tokenId: string): Promise<TokenDTO> {
+    return this.tokenApi.toggleTokenActive(tokenId);
+  }
+
+  /**
+   * ADMIN: Create new token
+   */
+  async createToken(tokenData: TokenCreateRequestDTO): Promise<TokenDTO> {
+    return this.tokenApi.createToken(tokenData);
+  }
+
+  /**
+   * ADMIN: Update token
+   */
+  async updateToken(tokenId: string, tokenData: TokenUpdateRequestDTO): Promise<TokenDTO> {
+    return this.tokenApi.updateToken(tokenId, tokenData);
+  }
+
+  /**
+   * ADMIN: Set mainnet contract address
+   */
+  async setMainnetContract(tokenId: string, contractAddress: string, chainId: number): Promise<TokenDTO> {
+    return this.tokenApi.setMainnetContract(tokenId, contractAddress, chainId);
+  }
+
+  /**
+   * ADMIN: Toggle token metadata status
+   */
+  async toggleTokenMetadataStatus(metadataId: string): Promise<TokenMetadataDTO> {
+    return this.tokenApi.toggleTokenMetadataStatus(metadataId);
+  }
+
+  /**
+   * ADMIN: Create token type
+   */
+  async createTokenType(tokenType: TokenTypeDTO): Promise<TokenTypeDTO> {
+    return this.tokenApi.createTokenType(tokenType);
+  }
+
+  // ❌ REMOVED: Business logic methods not present in framework
+  // - validateTokenMetadata() - Framework doesn't need this logic
+  // - processTokenTransaction() - Framework doesn't handle transactions
+  // These can be added later if actually needed
+}

package/src/token/token-sdk.ts

@@ -0,0 +1,231 @@
+import { TokenApi } from './api/token-api';
+import { TokenService } from './services/token-service';
+import { PersApiClient } from '../core/pers-api-client';
+import { 
+  TokenDTO,
+  TokenStorageData,
+  TokenCreateRequestDTO,
+  TokenUpdateRequestDTO,
+  TokenMetadataDTO
+} from './models';
+import { TokenTypeDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
+
+/**
+ * Token SDK - Class-based Promise SDK for Token Operations
+ * 
+ * Modern, performant SDK with direct method access and excellent TypeScript support.
+ * Optimized for bundle size, performance, and developer experience.
+ * 
+ * Usage:
+ *   const tokenSDK = new TokenSDK(apiClient);
+ *   const tokens = await tokenSDK.getTokens();
+ *   const creditToken = await tokenSDK.getActiveCreditToken();
+ */
+export class TokenSDK {
+  private readonly tokenApi: TokenApi;
+  private readonly tokenService: TokenService;
+  
+  constructor(apiClient: PersApiClient) {
+    this.tokenApi = new TokenApi(apiClient);
+    this.tokenService = new TokenService(this.tokenApi);
+  }
+
+  // ==========================================
+  // CONVENIENCE METHODS - Direct Promise API
+  // ==========================================
+  // Simplified method names for better developer experience
+
+  /**
+   * Get all tokens
+   * @returns Promise with all available tokens
+   */
+  async getTokens(): Promise<TokenDTO[]> {
+    return this.tokenService.getRemoteTokens();
+  }
+
+  /**
+   * Get all token types
+   * @returns Promise with all available token types
+   */
+  async getTokenTypes(): Promise<TokenTypeDTO[]> {
+    return this.tokenService.getRemoteTokenTypes();
+  }
+
+  /**
+   * Get the active credit token
+   * @returns Promise with the current active credit token
+   */
+  async getActiveCreditToken(): Promise<TokenDTO> {
+    return this.tokenService.getRemoteActiveCreditToken();
+  }
+
+  /**
+   * Get all reward tokens
+   * @returns Promise with all reward tokens
+   */
+  async getRewardTokens(): Promise<TokenDTO[]> {
+    return this.tokenService.getRemoteRewardTokens();
+  }
+
+  /**
+   * Get all status tokens
+   * @returns Promise with all status tokens
+   */
+  async getStatusTokens(): Promise<TokenDTO[]> {
+    return this.tokenService.getRemoteStatusTokens();
+  }
+
+  /**
+   * Get token by contract address
+   * @param contractAddress - The contract address to search for
+   * @param contractTokenId - Optional contract token ID
+   * @returns Promise with the matching token
+   */
+  async getTokenByContract(contractAddress: string, contractTokenId: string | null = null): Promise<TokenDTO> {
+    return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
+  }
+
+  // ==========================================
+  // ADMIN METHODS - Token Management
+  // ==========================================
+
+  /**
+   * Create token metadata
+   * @param tokenId - The token ID
+   * @param tokenData - The token storage data
+   * @returns Promise with the updated token
+   */
+  async createTokenMetadata(tokenId: string, tokenData: TokenStorageData): Promise<TokenDTO> {
+    return this.tokenService.createTokenMetadata(tokenId, tokenData);
+  }
+
+  /**
+   * Toggle token active status
+   * @param tokenId - The token ID to toggle
+   * @returns Promise with the updated token
+   */
+  async toggleTokenActive(tokenId: string): Promise<TokenDTO> {
+    return this.tokenService.toggleTokenActive(tokenId);
+  }
+
+  /**
+   * Create a new token
+   * @param tokenData - The token creation data
+   * @returns Promise with the created token
+   */
+  async createToken(tokenData: TokenCreateRequestDTO): Promise<TokenDTO> {
+    return this.tokenService.createToken(tokenData);
+  }
+
+  /**
+   * Update an existing token
+   * @param tokenId - The token ID to update
+   * @param tokenData - The token update data
+   * @returns Promise with the updated token
+   */
+  async updateToken(tokenId: string, tokenData: TokenUpdateRequestDTO): Promise<TokenDTO> {
+    return this.tokenService.updateToken(tokenId, tokenData);
+  }
+
+  /**
+   * Set mainnet contract address for a token
+   * @param tokenId - The token ID
+   * @param contractAddress - The contract address
+   * @param chainId - The blockchain chain ID
+   * @returns Promise with the updated token
+   */
+  async setMainnetContract(tokenId: string, contractAddress: string, chainId: number): Promise<TokenDTO> {
+    return this.tokenService.setMainnetContract(tokenId, contractAddress, chainId);
+  }
+
+  /**
+   * Toggle token metadata status
+   * @param metadataId - The metadata ID to toggle
+   * @returns Promise with the updated metadata
+   */
+  async toggleTokenMetadataStatus(metadataId: string): Promise<TokenMetadataDTO> {
+    return this.tokenService.toggleTokenMetadataStatus(metadataId);
+  }
+
+  /**
+   * Create a new token type
+   * @param tokenType - The token type data
+   * @returns Promise with the created token type
+   */
+  async createTokenType(tokenType: TokenTypeDTO): Promise<TokenTypeDTO> {
+    return this.tokenService.createTokenType(tokenType);
+  }
+
+  // ==========================================
+  // ADVANCED ACCESS - For Complex Operations
+  // ==========================================
+
+  /**
+   * Get direct access to the token service for advanced operations
+   * @returns The underlying TokenService instance
+   */
+  getTokenService(): TokenService {
+    return this.tokenService;
+  }
+
+  /**
+   * Get direct access to the token API for low-level operations
+   * @returns The underlying TokenApi instance
+   */
+  getTokenApi(): TokenApi {
+    return this.tokenApi;
+  }
+
+  // ==========================================
+  // FRAMEWORK COMPATIBILITY METHODS
+  // ==========================================
+  // These maintain compatibility with existing framework method names
+
+  /**
+   * @deprecated Use getTokens() instead
+   * Framework compatibility method
+   */
+  async getRemoteTokens(): Promise<TokenDTO[]> {
+    return this.getTokens();
+  }
+
+  /**
+   * @deprecated Use getTokenTypes() instead
+   * Framework compatibility method
+   */
+  async getRemoteTokenTypes(): Promise<TokenTypeDTO[]> {
+    return this.getTokenTypes();
+  }
+
+  /**
+   * @deprecated Use getActiveCreditToken() instead
+   * Framework compatibility method
+   */
+  async getRemoteActiveCreditToken(): Promise<TokenDTO> {
+    return this.getActiveCreditToken();
+  }
+
+  /**
+   * @deprecated Use getRewardTokens() instead
+   * Framework compatibility method
+   */
+  async getRemoteRewardTokens(): Promise<TokenDTO[]> {
+    return this.getRewardTokens();
+  }
+
+  /**
+   * @deprecated Use getStatusTokens() instead
+   * Framework compatibility method
+   */
+  async getRemoteStatusTokens(): Promise<TokenDTO[]> {
+    return this.getStatusTokens();
+  }
+
+  /**
+   * @deprecated Use getTokenByContract() instead
+   * Framework compatibility method
+   */
+  async getTokenByContractAddress(contractAddress: string, contractTokenId: string | null): Promise<TokenDTO> {
+    return this.getTokenByContract(contractAddress, contractTokenId);
+  }
+}