@explorins/pers-sdk 1.6.3 → 1.6.6

package/dist/managers/token-manager.d.ts

@@ -1,81 +1,305 @@
 import { PersApiClient } from '../core/pers-api-client';
-import { TokenSDK } from '../token';
-import type { TokenDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
+import { TokenService } from '../token';
+import type { TokenDTO } from '../token/models';
+import type { TokenTypeDTO } from '../shared/interfaces/pers-shared-lib.interfaces';
 /**
- * Token Manager - Clean, high-level interface for token operations
+ * Domain Token Manager - Clean, high-level interface for business token operations
  *
- * Provides a simplified API for common token management tasks while maintaining
- * access to the full token SDK for advanced use cases.
+ * Handles business domain tokens (reward tokens, credit tokens, NFTs, status tokens).
+ * This is separate from AuthTokenManager which handles authentication tokens.
+ *
+ * Provides a simplified API for token management including retrieving token information,
+ * managing different token types (credit, reward, status), and administrative operations.
+ * Maintains access to the full token SDK for advanced blockchain and token operations.
+ *
+ * @group Managers
+ * @category Token Management
+ *
+ * @example Basic Token Operations
+ * ```typescript
+ * // Get all available tokens
+ * const tokens = await sdk.tokens.getTokens();
+ * console.log(`Found ${tokens.length} tokens`);
+ *
+ * // Get active credit token
+ * const creditToken = await sdk.tokens.getActiveCreditToken();
+ * console.log('Credit token:', creditToken.name);
+ *
+ * // Get reward tokens
+ * const rewards = await sdk.tokens.getRewardTokens();
+ * ```
+ *
+ * @example Token Type Management
+ * ```typescript
+ * // Get all token types
+ * const types = await sdk.tokens.getTokenTypes();
+ *
+ * // Get status tokens for user progression
+ * const statusTokens = await sdk.tokens.getStatusTokens();
+ *
+ * // Get token by blockchain contract
+ * const token = await sdk.tokens.getTokenByContract('0x123...', 'token-id');
+ * ```
+ *
+ * @example Administrative Operations
+ * ```typescript
+ * // Admin: Create new token type
+ * const newToken = await sdk.tokens.createToken({
+ *   name: 'VIP Points',
+ *   symbol: 'VIP',
+ *   type: 'REWARD'
+ * });
+ *
+ * // Admin: Toggle token status
+ * await sdk.tokens.toggleTokenActive('token-123');
+ * ```
  */
 export declare class TokenManager {
     private apiClient;
-    private tokenSDK;
+    private tokenService;
     constructor(apiClient: PersApiClient);
     /**
      * Get all available tokens
      *
-     * @returns Promise resolving to array of tokens
+     * Retrieves all tokens available in the system, including credit tokens,
+     * reward tokens, and status tokens. This includes both active and inactive tokens.
+     *
+     * @returns Promise resolving to array of tokens with complete information
+     *
+     * @example
+     * ```typescript
+     * const tokens = await sdk.tokens.getTokens();
+     *
+     * tokens.forEach(token => {
+     *   console.log(`${token.name} (${token.symbol})`);
+     *   console.log(`Type: ${token.type}`);
+     *   console.log(`Active: ${token.isActive}`);
+     *   console.log(`Contract: ${token.contractAddress}`);
+     * });
+     * ```
      */
     getTokens(): Promise<TokenDTO[]>;
     /**
      * Get all token types
      *
-     * @returns Promise resolving to token types
+     * Retrieves the available token type definitions and their configurations.
+     * This includes metadata about how different token types behave in the system.
+     *
+     * @returns Promise resolving to token type configurations
+     *
+     * @example
+     * ```typescript
+     * const types = await sdk.tokens.getTokenTypes();
+     * console.log('Available token types:', types);
+     *
+     * // Use for token creation or validation
+     * const isValidType = types.some(type => type.name === 'REWARD');
+     * ```
      */
-    getTokenTypes(): Promise<import("@explorins/pers-shared").TokenTypeDTO[]>;
+    getTokenTypes(): Promise<TokenTypeDTO[]>;
     /**
      * Get active credit token
      *
+     * Retrieves the currently active credit token used for the main loyalty currency.
+     * There is typically only one active credit token per tenant.
+     *
      * @returns Promise resolving to active credit token
+     * @throws {PersApiError} When no active credit token is found
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const creditToken = await sdk.tokens.getActiveCreditToken();
+     *   console.log('Main loyalty currency:', creditToken.name);
+     *   console.log('Symbol:', creditToken.symbol);
+     *   console.log('Exchange rate:', creditToken.exchangeRate);
+     * } catch (error) {
+     *   console.log('No active credit token found');
+     * }
+     * ```
      */
     getActiveCreditToken(): Promise<TokenDTO>;
     /**
      * Get reward tokens
      *
-     * @returns Promise resolving to reward tokens
+     * Retrieves all tokens designated as rewards that can be earned through
+     * campaigns, challenges, or other loyalty activities.
+     *
+     * @returns Promise resolving to array of reward tokens
+     *
+     * @example
+     * ```typescript
+     * const rewardTokens = await sdk.tokens.getRewardTokens();
+     *
+     * console.log('Available rewards:');
+     * rewardTokens.forEach(token => {
+     *   console.log(`- ${token.name}: ${token.description}`);
+     * });
+     *
+     * // Use for campaign rewards or redemption options
+     * const discountToken = rewardTokens.find(t => t.name.includes('Discount'));
+     * ```
      */
     getRewardTokens(): Promise<TokenDTO[]>;
     /**
      * Get status tokens
      *
-     * @returns Promise resolving to status tokens
+     * Retrieves tokens that represent user status or achievement levels.
+     * These are typically used for user progression and tier systems.
+     *
+     * @returns Promise resolving to array of status tokens
+     *
+     * @example
+     * ```typescript
+     * const statusTokens = await sdk.tokens.getStatusTokens();
+     *
+     * console.log('Status levels available:');
+     * statusTokens.forEach(token => {
+     *   console.log(`${token.name} - ${token.description}`);
+     * });
+     *
+     * // Use for user tier display or progression tracking
+     * const vipToken = statusTokens.find(t => t.name === 'VIP Status');
+     * ```
      */
     getStatusTokens(): Promise<TokenDTO[]>;
     /**
      * Get token by contract address
      *
-     * @param contractAddress - Contract address to search for
-     * @param contractTokenId - Optional contract token ID
-     * @returns Promise resolving to token
+     * Retrieves a specific token by its blockchain contract address and optional
+     * token ID. Useful for blockchain integrations and Web3 operations.
+     *
+     * @param contractAddress - Blockchain contract address of the token
+     * @param contractTokenId - Optional specific token ID within the contract (for NFTs)
+     * @returns Promise resolving to matching token
+     * @throws {PersApiError} When token with specified contract address is not found
+     *
+     * @example ERC20 Token
+     * ```typescript
+     * // Get ERC20 token by contract address
+     * const token = await sdk.tokens.getTokenByContract('0x123...');
+     * console.log('ERC20 token:', token.name);
+     * ```
+     *
+     * @example NFT Token
+     * ```typescript
+     * // Get specific NFT by contract and token ID
+     * const nft = await sdk.tokens.getTokenByContract(
+     *   '0x456...',
+     *   'token-123'
+     * );
+     * console.log('NFT:', nft.name, 'ID:', nft.contractTokenId);
+     * ```
      */
-    getTokenByContract(contractAddress: string, contractTokenId?: string | null): Promise<TokenDTO>;
+    getTokenByContract(contractAddress: string, contractTokenId?: string): Promise<TokenDTO>;
     /**
      * Admin: Create new token
      *
-     * @param tokenData - Token creation data
+     * Creates a new token type in the system. This operation requires administrator
+     * privileges and is typically used for setting up new loyalty currencies,
+     * rewards, or status tokens.
+     *
+     * @param tokenData - Token creation data including name, symbol, type, and configuration
      * @returns Promise resolving to created token
+     * @throws {PersApiError} When not authenticated as admin or validation fails
+     *
+     * @example Create Credit Token
+     * ```typescript
+     * // Admin operation - create new loyalty currency
+     * const creditToken = await sdk.tokens.createToken({
+     *   name: 'Hotel Points',
+     *   symbol: 'HP',
+     *   type: 'CREDIT',
+     *   isActive: true,
+     *   exchangeRate: 1.0,
+     *   description: 'Main loyalty currency for hotel rewards'
+     * });
+     * ```
+     *
+     * @example Create Reward Token
+     * ```typescript
+     * // Admin operation - create new reward type
+     * const rewardToken = await sdk.tokens.createToken({
+     *   name: '10% Discount Coupon',
+     *   symbol: 'DISC10',
+     *   type: 'REWARD',
+     *   isActive: true,
+     *   description: '10% discount on next purchase'
+     * });
+     * ```
      */
     createToken(tokenData: any): Promise<TokenDTO>;
     /**
      * Admin: Update token
      *
-     * @param tokenId - Token ID to update
-     * @param tokenData - Token update data
+     * Updates an existing token's configuration. This operation requires administrator
+     * privileges and can modify token properties such as name, description, or status.
+     *
+     * @param tokenId - ID of the token to update
+     * @param tokenData - Token update data (partial update supported)
      * @returns Promise resolving to updated token
+     * @throws {PersApiError} When not authenticated as admin or token not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - update token configuration
+     * const updated = await sdk.tokens.updateToken('token-123', {
+     *   description: 'Updated token description',
+     *   exchangeRate: 1.25,
+     *   isActive: true
+     * });
+     *
+     * console.log('Token updated:', updated.name);
+     * ```
      */
     updateToken(tokenId: string, tokenData: any): Promise<TokenDTO>;
     /**
      * Admin: Toggle token active status
      *
-     * @param tokenId - Token ID to toggle
+     * Toggles the active/inactive status of a token. Inactive tokens are not
+     * available for new operations but existing holdings remain valid.
+     * Requires administrator privileges.
+     *
+     * @param tokenId - ID of the token to toggle
      * @returns Promise resolving to updated token
+     * @throws {PersApiError} When not authenticated as admin or token not found
+     *
+     * @example
+     * ```typescript
+     * // Admin operation - disable a token temporarily
+     * const updated = await sdk.tokens.toggleTokenActive('seasonal-token-123');
+     *
+     * if (updated.isActive) {
+     *   console.log('Token reactivated');
+     * } else {
+     *   console.log('Token deactivated');
+     * }
+     * ```
      */
     toggleTokenActive(tokenId: string): Promise<TokenDTO>;
     /**
      * Get the full token SDK for advanced operations
      *
-     * @returns TokenSDK instance
+     * Provides access to the complete TokenSDK instance for advanced blockchain
+     * operations, token balances, transfers, and other operations not covered
+     * by the high-level manager methods.
+     *
+     * @returns TokenSDK instance with full API access
+     *
+     * @example Advanced Operations
+     * ```typescript
+     * const tokenSDK = sdk.tokens.getTokenSDK();
+     *
+     * // Access token balance operations
+     * const balances = await tokenSDK.getTokenBalances('user-123');
+     *
+     * // Access blockchain operations
+     * const web3Operations = tokenSDK.getWeb3Operations();
+     *
+     * // Access token API directly
+     * const tokenApi = tokenSDK.api;
+     * ```
      */
-    getTokenSDK(): TokenSDK;
+    getTokenService(): TokenService;
 }
 //# sourceMappingURL=token-manager.d.ts.map

package/dist/managers/token-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/managers/token-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iDAAiD,CAAC;AAEhF;;;;;GAKG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,QAAQ,CAAW;gBAEP,SAAS,EAAE,aAAa;IAI5C;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAItC;;;;OAIG;IACG,aAAa;IAInB;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,QAAQ,CAAC;IAI/C;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI5C;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI5C;;;;;;OAMG;IACG,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIrG;;;;;OAKG;IACG,WAAW,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIpD;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIrE;;;;;OAKG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3D;;;;OAIG;IACH,WAAW,IAAI,QAAQ;CAKxB"}
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/managers/token-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAY,YAAY,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iDAAiD,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,YAAY,CAAe;gBAEf,SAAS,EAAE,aAAa;IAK5C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAItC;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa;IAInB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,oBAAoB,IAAI,OAAO,CAAC,QAAQ,CAAC;IAI/C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI5C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI5C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,WAAW,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIpD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIrE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,IAAI,YAAY;CAIhC"}