Skip to content
Last updated

PERS SDK - v2.3.26 / Exports / TransactionManager

Class: TransactionManager

Transaction Manager - Clean, high-level interface for transaction operations

Provides a comprehensive API for loyalty transaction management including transaction creation, history tracking, reporting, and administrative oversight. Transactions are the core financial operations that track token movements, purchases, rewards, and all value exchanges within the loyalty ecosystem.

Example

// Create a purchase transaction
const transaction = await sdk.transactions.createTransaction({
  type: 'PURCHASE',
  amount: 100.00,
  currency: 'USD',
  businessId: 'partner-store-123',
  description: 'Coffee shop purchase'
});

// Get transaction details
const details = await sdk.transactions.getTransactionById(transaction.id);
console.log('Transaction:', details.description, details.status);

// View transaction history
const history = await sdk.transactions.getUserTransactionHistory('ALL');
console.log(`Found ${history.length} transactions`);

Example

// Get different types of transactions
const purchases = await sdk.transactions.getUserTransactionHistory('PURCHASE');
const rewards = await sdk.transactions.getUserTransactionHistory('REWARD');
const redemptions = await sdk.transactions.getUserTransactionHistory('REDEMPTION');

console.log('Transaction Summary:');
console.log(`Purchases: ${purchases.length}`);
console.log(`Rewards: ${rewards.length}`);
console.log(`Redemptions: ${redemptions.length}`);

Example

// Admin: Get paginated transactions for analysis
const allTransactions = await sdk.transactions.getPaginatedTransactions({ page: 1, limit: 100 });

// Export transaction data
const csvBlob = await sdk.transactions.exportTransactionsCSV();
const downloadUrl = URL.createObjectURL(csvBlob);
console.log('Download transaction report:', downloadUrl);

Table of contents

Constructors

Methods

Constructors

constructor

• new TransactionManager(apiClient, events?): TransactionManager

Parameters

NameType
apiClientPersApiClient
events?PersEventEmitter

Returns

TransactionManager

Defined in

managers/transaction-manager.ts:65

Methods

getTransactionById

▸ getTransactionById(transactionId, include?): Promise<TransactionDTO>

Get transaction by ID

Retrieves detailed information for a specific transaction including status, amounts, participants, token transfers, and blockchain confirmations. Provides complete transaction audit trail and verification data.

Parameters

NameTypeDescription
transactionIdstringUnique transaction identifier
include?TransactionIncludeRelation[]Optional relations to include (sender, recipient, business) for enriched entity data

Returns

Promise<TransactionDTO>

Promise resolving to complete transaction data

Throws

When transaction with specified ID is not found or access denied

Example

try {
  // Get transaction with enriched sender/recipient data
  const transaction = await sdk.transactions.getTransactionById(
    'txn-abc123',
    ['sender', 'recipient', 'business']
  );
  
  console.log('Transaction Details:');
  console.log('ID:', transaction.id);
  console.log('Type:', transaction.type);
  console.log('Status:', transaction.status);
  console.log('Amount:', transaction.amount, transaction.currency);
  console.log('Date:', new Date(transaction.createdAt).toLocaleString());
  
  if (transaction.description) {
    console.log('Description:', transaction.description);
  }
  
  // Access enriched sender data
  if (transaction.included?.sender) {
    console.log('Sender:', transaction.included.sender);
  }
  
  // Access enriched recipient data
  if (transaction.included?.recipient) {
    console.log('Recipient:', transaction.included.recipient);
  }
  
  // Access enriched business data
  if (transaction.included?.engagedBusiness) {
    console.log('Business:', transaction.included.engagedBusiness.displayName);
  }
  
  // Show blockchain confirmation
  if (transaction.blockchainHash) {
    console.log('Blockchain:', transaction.blockchainHash);
  }
  
} catch (error) {
  console.log('Transaction not found or access denied:', error.message);
}

Defined in

managers/transaction-manager.ts:130


createTransaction

▸ createTransaction(transactionData): Promise<TransactionRequestResponseDTO>

Create a new transaction

Creates a new transaction in the loyalty system, processing token transfers, applying rewards, and updating user balances. Supports various transaction types including purchases, rewards, redemptions, and transfers.

Parameters

NameTypeDescription
transactionDataTransactionRequestDTOTransaction configuration including type, amounts, and context

Returns

Promise<TransactionRequestResponseDTO>

Promise resolving to transaction creation response

Throws

When validation fails or insufficient balance

Example

try {
  const purchase = await sdk.transactions.createTransaction({
    type: 'PURCHASE',
    amount: 25.50,
    currency: 'USD',
    businessId: 'coffee-shop-123',
    description: 'Morning coffee and pastry',
    metadata: {
      items: ['Latte', 'Croissant'],
      location: 'Downtown Store'
    }
  });
  
  console.log('Purchase completed!');
  console.log('Transaction ID:', purchase.id);
  console.log('Status:', purchase.status);
  
  if (purchase.tokensEarned?.length) {
    console.log('\nLoyalty rewards earned:');
    purchase.tokensEarned.forEach(reward => {
      console.log(`${reward.amount} ${reward.token.symbol}`);
    });
  }
  
} catch (error) {
  console.log('Transaction failed:', error.message);
}

Example

// Create reward transaction (typically triggered by campaigns)
const reward = await sdk.transactions.createTransaction({
  type: 'REWARD',
  businessId: 'partner-hotel-456',
  description: 'Welcome bonus for new customer',
  tokenRewards: [
    {
      tokenId: 'loyalty-points',
      amount: 500
    }
  ]
});

console.log('Reward transaction created:', reward.id);

Example

// Create token transfer between users
const transfer = await sdk.transactions.createTransaction({
  type: 'TRANSFER',
  recipientUserId: 'user-789',
  description: 'Gift to friend',
  tokenTransfers: [
    {
      tokenId: 'loyalty-points',
      amount: 100,
      direction: 'OUTBOUND'
    }
  ]
});

console.log('Transfer initiated:', transfer.id);

Defined in

managers/transaction-manager.ts:216


getUserTransactionHistory

▸ getUserTransactionHistory(options?): Promise<PaginatedResponseDTO<TransactionDTO>>

Get user's transaction history

Retrieves transaction history for the authenticated user with comprehensive filtering options. Provides chronological view of all user's loyalty activities including purchases, rewards, redemptions, and transfers. Optionally enrich with related entities (sender, recipient, business).

Parameters

NameTypeDescription
options?TransactionQueryParamsQuery options including filters, pagination, and include relations

Returns

Promise<PaginatedResponseDTO<TransactionDTO>>

Promise resolving to paginated transaction data with optional included entities

Example

const result = await sdk.transactions.getUserTransactionHistory();

console.log(`Transaction History (${result.data.length} of ${result.pagination.total} transactions)`);

result.data.forEach((transaction, index) => {
  const date = new Date(transaction.createdAt).toLocaleDateString();
  console.log(`\n${index + 1}. ${transaction.type} - ${date}`);
  console.log(`   ${transaction.description || 'No description'}`);
  console.log(`   Status: ${transaction.status}`);
});

Example

// Get only completed sent transactions
const sent = await sdk.transactions.getUserTransactionHistory({
  role: TransactionRole.SENDER,
  status: TransactionStatus.COMPLETED,
  include: ['recipient', 'business'],
  page: 1,
  limit: 50
});

sent.data.forEach(tx => {
  console.log(`Sent to: ${tx.included?.recipient?.displayName || tx.recipientAddress}`);
});

Example

// Get all transactions triggered by a specific campaign claim
const claimTxs = await sdk.transactions.getUserTransactionHistory({
  triggerProcessId: 'claim-abc123',
  include: ['sender', 'recipient', 'business']
});

claimTxs.data.forEach(tx => {
  console.log('Transaction from claim:', tx.id);
  if (tx.included?.engagedBusiness) {
    console.log('Business:', tx.included.engagedBusiness.displayName);
  }
});

Defined in

managers/transaction-manager.ts:286


getPaginatedTransactions

▸ getPaginatedTransactions(options): Promise<PaginatedResponseDTO<TransactionDTO>>

Admin: Get paginated transactions

Retrieves transactions with pagination support for efficient large dataset handling. This operation requires administrator privileges and is used for detailed transaction analysis and reporting interfaces.

Parameters

NameTypeDescription
optionsTransactionPaginationRequestDTO & { include?: TransactionIncludeRelation[] }Pagination, filtering parameters, and optional include relations

Returns

Promise<PaginatedResponseDTO<TransactionDTO>>

Promise resolving to paginated transaction results with metadata

Throws

When not authenticated as administrator

Example

// Admin operation - paginated transaction retrieval
const result = await sdk.transactions.getPaginatedTransactions({
  page: 1,
  limit: 50,
  sortBy: 'createdAt',
  sortOrder: 'DESC'
});

console.log(`� Page ${result.page} of ${result.totalPages}`);
console.log(`Showing ${result.data.length} of ${result.total} transactions`);

result.data.forEach((transaction, index) => {
  console.log(`${index + 1}. ${transaction.type} - ${transaction.status}`);
  console.log(`   ${new Date(transaction.createdAt).toLocaleDateString()}`);
});

// Continue pagination if needed
if (result.hasNextPage) {
  const nextPage = await sdk.transactions.getPaginatedTransactions({
    page: result.page + 1,
    limit: 50
  });
}

Example

// Admin operation - filter transactions by criteria
const filteredResult = await sdk.transactions.getPaginatedTransactions({
  page: 1,
  limit: 25,
  filters: {
    type: 'PURCHASE',
    status: 'COMPLETED',
    businessId: 'partner-store-123',
    dateFrom: '2024-01-01',
    dateTo: '2024-12-31'
  },
  sortBy: 'amount',
  sortOrder: 'DESC'
});

console.log('Filtered Results:');
console.log(`Found ${filteredResult.total} matching transactions`);

filteredResult.data.forEach(transaction => {
  console.log(`$${transaction.amount} - ${transaction.business?.displayName}`);
});

Example

// Include sender and recipient entities
const result = await sdk.transactions.getPaginatedTransactions({
  page: 1,
  limit: 50,
  include: ['sender', 'recipient', 'business']
});

result.data.forEach(tx => {
  if (tx.included?.sender) console.log('From:', tx.included.sender);
  if (tx.included?.recipient) console.log('To:', tx.included.recipient);
});

Defined in

managers/transaction-manager.ts:370


exportCSV

▸ exportCSV(options?): Promise<Blob>

Admin: Export transactions as CSV

Generates a comprehensive CSV export of all tenant transactions for external analysis, reporting, or compliance purposes. This operation requires administrator privileges and creates a downloadable file.

Parameters

NameTypeDescription
options?ObjectOptional date range filters
options.dateFrom?stringStart date filter (ISO date string)
options.dateTo?stringEnd date filter (ISO date string)

Returns

Promise<Blob>

Promise resolving to CSV blob for download

Throws

When not authenticated as administrator or export fails

Example

const csvBlob = await sdk.transactions.exportCSV();
const downloadUrl = URL.createObjectURL(csvBlob);

Example

const csvBlob = await sdk.transactions.exportCSV({
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31'
});

Defined in

managers/transaction-manager.ts:405


exportTransactionsCSV

▸ exportTransactionsCSV(options?): Promise<Blob>

Admin: Export transactions as CSV

Parameters

NameType
options?Object
options.dateFrom?string
options.dateTo?string

Returns

Promise<Blob>

Deprecated

Use exportCSV() instead for consistent naming across all managers

Defined in

managers/transaction-manager.ts:414


prepareExistingTransaction

▸ prepareExistingTransaction(transactionId): Promise<TransactionRequestResponseDTO>

Prepare existing transaction for client-side signing

Retrieves the necessary data to sign an existing transaction on the client side. This is typically used when a transaction has been created but requires user signature.

Parameters

NameTypeDescription
transactionIdstringThe ID of the transaction to prepare

Returns

Promise<TransactionRequestResponseDTO>

Promise resolving to the transaction preparation data

Defined in

managers/transaction-manager.ts:427


prepareClientSignedTransaction

▸ prepareClientSignedTransaction(request): Promise<TransactionRequestResponseDTO>

Prepare a new transaction for client-side signing

Creates a new transaction and immediately returns the data needed for client-side signing. This combines creation and preparation into a single flow for client-signed operations.

Parameters

NameTypeDescription
requestTransactionRequestDTOThe transaction request details

Returns

Promise<TransactionRequestResponseDTO>

Promise resolving to the transaction preparation data

Defined in

managers/transaction-manager.ts:440


submitSignedTransaction

▸ submitSignedTransaction(signedTxData): Promise<TransactionRequestResponseDTO>

Submit a signed transaction

Submits a transaction that has been signed on the client side to the backend for processing.

Parameters

NameTypeDescription
signedTxDataTransactionSubmissionRequestDTOThe signed transaction data

Returns

Promise<TransactionRequestResponseDTO>

Promise resolving to the submission result

Defined in

managers/transaction-manager.ts:452


queryTransactionsBySender

▸ queryTransactionsBySender(accountSelector): Promise<PaginatedResponseDTO<TransactionDTO>>

Query transactions by sender

Retrieves transactions where the specified account is the sender.

Parameters

NameTypeDescription
accountSelectorAccountSelectorDTOSelector for the sender account

Returns

Promise<PaginatedResponseDTO<TransactionDTO>>

Promise resolving to paginated transactions

Defined in

managers/transaction-manager.ts:473


queryTransactionsByRecipient

▸ queryTransactionsByRecipient(accountSelector): Promise<PaginatedResponseDTO<TransactionDTO>>

Query transactions by recipient

Retrieves transactions where the specified account is the recipient.

Parameters

NameTypeDescription
accountSelectorAccountSelectorDTOSelector for the recipient account

Returns

Promise<PaginatedResponseDTO<TransactionDTO>>

Promise resolving to paginated transactions

Defined in

managers/transaction-manager.ts:485


getTransactionAnalytics

▸ getTransactionAnalytics(analyticsRequest): Promise<TransactionAnalyticsResponseDTO>

Get transaction analytics

Retrieves analytics data for transactions based on the provided request criteria. Useful for generating reports and dashboards.

Parameters

NameTypeDescription
analyticsRequestTransactionAnalyticsRequestDTOThe analytics query parameters

Returns

Promise<TransactionAnalyticsResponseDTO>

Promise resolving to the analytics data

Defined in

managers/transaction-manager.ts:498


getTransactionService

▸ getTransactionService(): TransactionService

Get the full transaction service for advanced operations

Provides access to the complete TransactionService instance for advanced transaction operations, custom analytics, blockchain interactions, and operations not covered by the high-level manager methods.

Returns

TransactionService

TransactionService instance with full API access

Example

const transactionService = sdk.transactions.getTransactionService();

// Access advanced transaction analytics
const analytics = await transactionService.getTransactionAnalytics({
  timeframe: 'last-30-days',
  groupBy: 'business'
});

// Access blockchain transaction monitoring
const blockchainStatus = await transactionService.getBlockchainTransactionStatus('txn-123');

// Access transaction API directly
const transactionApi = transactionService.api;

// Use advanced validation and verification
const verification = await transactionService.verifyTransactionIntegrity('txn-456');

// Access real-time transaction streaming
const stream = transactionService.subscribeToTransactionUpdates();
stream.on('transaction', (transaction) => {
  console.log('New transaction:', transaction.id);
});

Defined in

managers/transaction-manager.ts:537