PERS SDK - v2.3.26 / Exports / 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);- getTransactionById
- createTransaction
- getUserTransactionHistory
- getPaginatedTransactions
- exportCSV
- exportTransactionsCSV
- prepareExistingTransaction
- prepareClientSignedTransaction
- submitSignedTransaction
- queryTransactionsBySender
- queryTransactionsByRecipient
- getTransactionAnalytics
- getTransactionService
• new TransactionManager(apiClient, events?): TransactionManager
| Name | Type |
|---|---|
apiClient | PersApiClient |
events? | PersEventEmitter |
managers/transaction-manager.ts:65
▸ 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.
| Name | Type | Description |
|---|---|---|
transactionId | string | Unique transaction identifier |
include? | TransactionIncludeRelation[] | Optional relations to include (sender, recipient, business) for enriched entity data |
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);
}managers/transaction-manager.ts:130
▸ 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.
| Name | Type | Description |
|---|---|---|
transactionData | TransactionRequestDTO | Transaction configuration including type, amounts, and context |
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);managers/transaction-manager.ts:216
▸ 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).
| Name | Type | Description |
|---|---|---|
options? | TransactionQueryParams | Query options including filters, pagination, and include relations |
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);
}
});managers/transaction-manager.ts:286
▸ 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.
| Name | Type | Description |
|---|---|---|
options | TransactionPaginationRequestDTO & { include?: TransactionIncludeRelation[] } | Pagination, filtering parameters, and optional include relations |
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);
});managers/transaction-manager.ts:370
▸ 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.
| Name | Type | Description |
|---|---|---|
options? | Object | Optional date range filters |
options.dateFrom? | string | Start date filter (ISO date string) |
options.dateTo? | string | End date filter (ISO date string) |
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'
});managers/transaction-manager.ts:405
▸ exportTransactionsCSV(options?): Promise<Blob>
Admin: Export transactions as CSV
| Name | Type |
|---|---|
options? | Object |
options.dateFrom? | string |
options.dateTo? | string |
Promise<Blob>
Deprecated
Use exportCSV() instead for consistent naming across all managers
managers/transaction-manager.ts:414
▸ 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.
| Name | Type | Description |
|---|---|---|
transactionId | string | The ID of the transaction to prepare |
Promise<TransactionRequestResponseDTO>
Promise resolving to the transaction preparation data
managers/transaction-manager.ts:427
▸ 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.
| Name | Type | Description |
|---|---|---|
request | TransactionRequestDTO | The transaction request details |
Promise<TransactionRequestResponseDTO>
Promise resolving to the transaction preparation data
managers/transaction-manager.ts:440
▸ submitSignedTransaction(signedTxData): Promise<TransactionRequestResponseDTO>
Submit a signed transaction
Submits a transaction that has been signed on the client side to the backend for processing.
| Name | Type | Description |
|---|---|---|
signedTxData | TransactionSubmissionRequestDTO | The signed transaction data |
Promise<TransactionRequestResponseDTO>
Promise resolving to the submission result
managers/transaction-manager.ts:452
▸ queryTransactionsBySender(accountSelector): Promise<PaginatedResponseDTO<TransactionDTO>>
Query transactions by sender
Retrieves transactions where the specified account is the sender.
| Name | Type | Description |
|---|---|---|
accountSelector | AccountSelectorDTO | Selector for the sender account |
Promise<PaginatedResponseDTO<TransactionDTO>>
Promise resolving to paginated transactions
managers/transaction-manager.ts:473
▸ queryTransactionsByRecipient(accountSelector): Promise<PaginatedResponseDTO<TransactionDTO>>
Query transactions by recipient
Retrieves transactions where the specified account is the recipient.
| Name | Type | Description |
|---|---|---|
accountSelector | AccountSelectorDTO | Selector for the recipient account |
Promise<PaginatedResponseDTO<TransactionDTO>>
Promise resolving to paginated transactions
managers/transaction-manager.ts:485
▸ getTransactionAnalytics(analyticsRequest): Promise<TransactionAnalyticsResponseDTO>
Get transaction analytics
Retrieves analytics data for transactions based on the provided request criteria. Useful for generating reports and dashboards.
| Name | Type | Description |
|---|---|---|
analyticsRequest | TransactionAnalyticsRequestDTO | The analytics query parameters |
Promise<TransactionAnalyticsResponseDTO>
Promise resolving to the analytics data
managers/transaction-manager.ts:498
▸ 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.
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);
});