Statements API

The Statement Service generates formal account statements for users and vendors, with export capabilities for CSV and HTML/PDF.

Overview

Account statements show:

• Opening and closing balances
• All transactions in a period
• Running balances after each entry
• Transaction summaries

Service Methods

generateStatement(accountCode, entityId, entityType, options)

Generate a statement for any entity and account.

Parameters:

Parameter	Type	Required	Description
accountCode	string	Yes	Account code (e.g., 1110)
entityId	string	Yes	User or Vendor ID
entityType	string	Yes	User or Vendor
options.startDate	Date	No	Period start (default: 30 days ago)
options.endDate	Date	No	Period end (default: now)
options.includeCounterpartyNames	boolean	No	Include names in entries

Returns:

interface AccountStatement {
  accountCode: string;
  accountName: string;
  entityId: string;
  entityName: string;
  entityType: string;
  startDate: Date;
  endDate: Date;
  openingBalance: number;
  closingBalance: number;
  totalDebits: number;
  totalCredits: number;
  entries: StatementEntry[];
  generatedAt: Date;
}

interface StatementEntry {
  date: Date;
  entryId: string;
  journalId: string;
  description: string;
  reference?: string;
  debit: number;
  credit: number;
  balance: number;
  counterpartyName?: string;
  counterpartyType?: string;
}

---

generateUserStatement(userId, options)

Convenience method for user wallet statements (account 1110).

Parameters:

Parameter	Type	Description
userId	string	User ID
options.startDate	Date	Period start
options.endDate	Date	Period end
options.includeCounterpartyNames	boolean	Include names

Returns: AccountStatement

Example:

const statement = await statementService.generateUserStatement('user-123', {
  startDate: new Date('2026-01-01'),
  endDate: new Date('2026-01-31'),
  includeCounterpartyNames: true
});

console.log(`Opening: E${statement.openingBalance.toFixed(2)}`);
console.log(`Closing: E${statement.closingBalance.toFixed(2)}`);
console.log(`Transactions: ${statement.entries.length}`);

---

generateVendorStatement(vendorId, options)

Convenience method for vendor wallet statements (account 1120).

Returns: AccountStatement

---

exportToCSV(statement)

Export statement to CSV format.

Parameters:

Parameter	Type	Description
statement	AccountStatement	Statement to export

Returns: CSV string

CSV Format:

Account Statement - User Wallets
Entity: John Doe (User)
Period: 1/1/2026 to 1/31/2026
Generated: 1/24/2026, 10:30:00 AM

Opening Balance,,,E500.00

Date,Description,Reference,Debit,Credit,Balance,Counterparty
1/5/2026,P2P Transfer,TXN-001,,E50.00,E450.00,Jane Smith
1/10/2026,Top-up,TXN-002,E100.00,,E550.00,Cash Agent

Total Debits,,,E100.00,,,
Total Credits,,,,E50.00,,
Closing Balance,,,,,E550.00,

---

exportToHTML(statement)

Export statement to HTML format (PDF-ready).

Returns: Complete HTML document with styling

Features:

• Professional formatting
• Color-coded debits (red) and credits (green)
• Summary section
• Print-ready layout

---

getTransactionSummary(entityId, entityType, options)

Get a summary of transaction activity for a period.

Parameters:

Parameter	Type	Description
entityId	string	User or Vendor ID
entityType	string	User or Vendor
options.startDate	Date	Period start
options.endDate	Date	Period end

Returns:

{
  totalTransactions: number;
  totalDeposits: number;
  totalWithdrawals: number;
  netChange: number;
  largestDeposit: number;
  largestWithdrawal: number;
  averageTransactionSize: number;
}

Example:

const summary = await statementService.getTransactionSummary(
  'user-123',
  'User',
  {
    startDate: new Date('2026-01-01'),
    endDate: new Date('2026-01-31')
  }
);

console.log(`Total Transactions: ${summary.totalTransactions}`);
console.log(`Net Change: E${summary.netChange.toFixed(2)}`);
console.log(`Largest Deposit: E${summary.largestDeposit.toFixed(2)}`);

---

Statement Entry Details

Each statement entry includes:

Field	Description
date	Transaction date
entryId	Ledger entry ID (e.g., LE-000456)
journalId	Parent journal ID (e.g., JE-000123)
description	Transaction description
reference	Original transaction ID
debit	Amount added to account
credit	Amount removed from account
balance	Running balance after entry
counterpartyName	Other party's name (if requested)
counterpartyType	User, Vendor, or System

---

Default Accounts

Entity Type	Account Code	Account Name
User	1110	User Wallets
Vendor	1120	Vendor Wallets

---

Period Defaults

When no dates are specified:

• Start Date: 30 days before end date
• End Date: Current date/time

---

Export Formats

CSV Export

• Compatible with Excel, Google Sheets
• Includes metadata header
• Proper escaping for special characters

HTML Export

• Print-ready styling
• Mobile-responsive
• Can be converted to PDF using browser print

---

API Endpoints

Endpoint	Method	Description
/api/users/:id/statement	GET	User statement
/api/vendors/:id/statement	GET	Vendor statement
/api/statements/:id/csv	GET	CSV export
/api/statements/:id/pdf	GET	PDF export

Query Parameters:

• startDate - ISO date string
• endDate - ISO date string
• includeCounterparty - boolean

---

Dashboard Integration

Access statements in the admin dashboard:

• User Statement: /admin/users/:id/statement
• Vendor Statement: /admin/vendors/:id/statement

---

Related

• Ledger Service - Core ledger operations
• Trial Balance - Balance reports
• Balance Verification - Reconciliation