fix(documentation): Updated documentation in readme.md
This commit is contained in:
parent
2bc50c6714
commit
aa8fd8b47d
@ -1,5 +1,12 @@
|
||||
# Changelog
|
||||
|
||||
## 2024-07-05 - 1.0.28 - fix(documentation)
|
||||
Updated documentation in readme.md
|
||||
|
||||
- Fixed and elaborated on the installation steps for npm and yarn.
|
||||
- Added usage examples and interfaces overview sections.
|
||||
- Included sections on advanced usage scenarios like handling multiple CSV files, transaction filtering and aggregation.
|
||||
|
||||
## 2024-07-02 - 1.0.27 - fix(core)
|
||||
Fix npm package availability links and status badges in readme.md
|
||||
|
||||
|
||||
@ -5,10 +5,19 @@
|
||||
"githost": "gitlab.com",
|
||||
"gitscope": "fin.cx",
|
||||
"gitrepo": "portablefinance",
|
||||
"description": "an interface package for the financeplus organization",
|
||||
"description": "An interface package for handling financial transactions and account data within the financeplus organization.",
|
||||
"npmPackagename": "@fin.cx/portablefinance",
|
||||
"license": "MIT",
|
||||
"projectDomain": "fin.cx"
|
||||
"projectDomain": "fin.cx",
|
||||
"keywords": [
|
||||
"finance",
|
||||
"financial transactions",
|
||||
"payment accounts",
|
||||
"interfaces",
|
||||
"vouchers",
|
||||
"csv",
|
||||
"typescript"
|
||||
]
|
||||
}
|
||||
},
|
||||
"npmci": {
|
||||
|
||||
15
package.json
15
package.json
@ -2,7 +2,7 @@
|
||||
"name": "@fin.cx/portablefinance",
|
||||
"version": "1.0.27",
|
||||
"private": false,
|
||||
"description": "an interface package for the financeplus organization",
|
||||
"description": "An interface package for handling financial transactions and account data within the financeplus organization.",
|
||||
"main": "dist_ts/index.js",
|
||||
"typings": "dist_ts/index.d.ts",
|
||||
"author": "Lossless GmbH",
|
||||
@ -42,5 +42,14 @@
|
||||
"url": "https://gitlab.com/fin.cx/portablefinance/issues"
|
||||
},
|
||||
"homepage": "https://gitlab.com/fin.cx/portablefinance#readme",
|
||||
"type": "module"
|
||||
}
|
||||
"type": "module",
|
||||
"keywords": [
|
||||
"finance",
|
||||
"financial transactions",
|
||||
"payment accounts",
|
||||
"interfaces",
|
||||
"vouchers",
|
||||
"csv",
|
||||
"typescript"
|
||||
]
|
||||
}
|
||||
247
readme.md
247
readme.md
@ -1,36 +1,235 @@
|
||||
# @fin.cx/portablefinance
|
||||
an interface package for the financeplus organization
|
||||
|
||||
## Availabililty and Links
|
||||
* [npmjs.org (npm package)](https://www.npmjs.com/package/@financeplus/finplus-interfaces)
|
||||
* [gitlab.com (source)](https://gitlab.com/financeplus/finplus-interfaces)
|
||||
* [github.com (source mirror)](https://github.com/financeplus/finplus-interfaces)
|
||||
* [docs (typedoc)](https://financeplus.gitlab.io/finplus-interfaces/)
|
||||
## Install
|
||||
To install the `@fin.cx/portablefinance` package, you can use npm or yarn. Make sure you have Node.js installed on your machine.
|
||||
|
||||
## Status for master
|
||||
Using npm:
|
||||
|
||||
Status Category | Status Badge
|
||||
-- | --
|
||||
GitLab Pipelines | [](https://lossless.cloud)
|
||||
GitLab Pipline Test Coverage | [](https://lossless.cloud)
|
||||
npm | [](https://lossless.cloud)
|
||||
Snyk | [](https://lossless.cloud)
|
||||
TypeScript Support | [](https://lossless.cloud)
|
||||
node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/)
|
||||
Code Style | [](https://lossless.cloud)
|
||||
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
|
||||
PackagePhobia (package size on registry) | [](https://lossless.cloud)
|
||||
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
|
||||
Platform support | [](https://lossless.cloud) [](https://lossless.cloud)
|
||||
```sh
|
||||
npm install @fin.cx/portablefinance
|
||||
```
|
||||
|
||||
Using yarn:
|
||||
|
||||
```sh
|
||||
yarn add @fin.cx/portablefinance
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```typescript
|
||||
import {
|
||||
AcCsvParser,
|
||||
IMonetaryTransaction,
|
||||
IPaymentAccount,
|
||||
IMonthlyCheckpoint,
|
||||
IVoucher,
|
||||
ICsvDescriptor
|
||||
} from '@fin.cx/portablefinance';
|
||||
|
||||
## Contribution
|
||||
// 1. Define a CSV Parser
|
||||
class MyCsvParser extends AcCsvParser<IMonetaryTransaction> {
|
||||
public paymentProviderName = 'mybank';
|
||||
public description = 'Custom CSV Parser for MyBank';
|
||||
private transactions: IMonetaryTransaction[] = [];
|
||||
|
||||
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
|
||||
public addCsvDecriptor(csvDescriptorArg: ICsvDescriptor): void {
|
||||
// Implement the logic to parse the CSV and populate transactions array
|
||||
// For simplicity, assume the CSV is correctly formatted and contains the necessary transaction details.
|
||||
this.transactions = [
|
||||
{
|
||||
id: 'txn1',
|
||||
data: {
|
||||
paymentAccountId: 'acc1',
|
||||
originTransactionId: 'orig1',
|
||||
originAccountId: 'origAcc1',
|
||||
additionalIds: ['add1', 'add2'],
|
||||
date: Date.now(),
|
||||
amount: 1000,
|
||||
description: 'Payment for services',
|
||||
name: 'Service Payment',
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
|
||||
For further information read the linked docs at the top of this readme.
|
||||
public async getTransactions(): Promise<IMonetaryTransaction[]> {
|
||||
return this.transactions;
|
||||
}
|
||||
}
|
||||
|
||||
> MIT licensed | **©** [Task Venture Capital GmbH](https://lossless.gmbh)
|
||||
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
|
||||
// 2. Define a Payment Account
|
||||
const myVoucher: IVoucher = {
|
||||
voucherDate: new Date(),
|
||||
voucherId: 'vch1',
|
||||
voucherStatus: 'uploaded',
|
||||
voucherBinaryString: 'binarystringdata',
|
||||
};
|
||||
|
||||
const myAccount: IPaymentAccount = {
|
||||
id: 'acc1',
|
||||
data: {
|
||||
status: 'active',
|
||||
connectionData: {
|
||||
bankAdapterType: 'mybank',
|
||||
credentials: {
|
||||
username: 'user',
|
||||
password: 'pass',
|
||||
},
|
||||
},
|
||||
currency: 'USD',
|
||||
name: 'MyBankAccount',
|
||||
checkpoints: {
|
||||
'2021': {
|
||||
1: {
|
||||
start: new Date('2021-01-01').getTime(),
|
||||
end: new Date('2021-01-31').getTime(),
|
||||
pdfVoucher: myVoucher,
|
||||
},
|
||||
2: {
|
||||
start: new Date('2021-02-01').getTime(),
|
||||
end: new Date('2021-02-28').getTime(),
|
||||
pdfVoucher: myVoucher,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
// 3. Working with Transactions and Accounts
|
||||
(async () => {
|
||||
const csvParser = new MyCsvParser();
|
||||
const csvDescriptor: ICsvDescriptor = {
|
||||
name: 'transactions.csv',
|
||||
contentString: 'dummy content', // Replace with actual CSV content
|
||||
};
|
||||
|
||||
csvParser.addCsvDecriptor(csvDescriptor);
|
||||
|
||||
const transactions = await csvParser.getTransactions();
|
||||
console.log('Parsed Transactions:', transactions);
|
||||
|
||||
console.log('Payment Account:', myAccount);
|
||||
})();
|
||||
```
|
||||
|
||||
In this example, we demonstrate how to:
|
||||
|
||||
1. Define a custom CSV parser class (`MyCsvParser`) that extends the `AcCsvParser` abstract class.
|
||||
2. Implement the `addCsvDecriptor` method to parse CSV content and populate transactions.
|
||||
3. Define a sample payment account (`myAccount`) with necessary details.
|
||||
4. Integrate the parser and account information in an asynchronous function to showcase the usage of parsed transactions and account data.
|
||||
|
||||
### Interfaces Overview
|
||||
|
||||
#### IVoucher Interface
|
||||
The `IVoucher` interface is used to represent payment vouchers, with the following fields:
|
||||
|
||||
* `voucherDate`: Date – The date the voucher was created.
|
||||
* `voucherId`: string – Unique identifier for the voucher.
|
||||
* `voucherStatus`: 'uploaded' | 'transmitted' – The status of the voucher.
|
||||
* `voucherBinaryString`: string – The binary string representation of the voucher content.
|
||||
|
||||
#### IMonetaryTransaction Interface
|
||||
The `IMonetaryTransaction` interface is used to represent monetary transactions, with the following fields:
|
||||
|
||||
* `id`: string – Unique identifier for the transaction.
|
||||
* `data`: object – Contains key details about the transaction:
|
||||
* `paymentAccountId`: string – Identifier for the payment account involved in the transaction.
|
||||
* `originTransactionId`: string – Identifier for the original transaction (in case of related transactions).
|
||||
* `originAccountId`: string – Identifier for the account from where the transaction originated.
|
||||
* `additionalIds`: string[] – Additional identifiers related to the transaction.
|
||||
* `date`: number – Date of the transaction (timestamp).
|
||||
* `amount`: number – Amount involved in the transaction.
|
||||
* `description`: string – Description of the transaction.
|
||||
* `name`: string – Name associated with the transaction.
|
||||
* Optional properties for additional voucher data and metadata.
|
||||
|
||||
#### IPaymentAccount Interface
|
||||
The `IPaymentAccount` interface represents a payment account with various properties, organized into nested structures.
|
||||
|
||||
* `id`: string – Unique identifier for the payment account.
|
||||
* `data`: object – Contains the core data for the payment account:
|
||||
* `status`: 'active' | 'inactive' | 'deleted' – Status of the account.
|
||||
* `connectionData`: object – Holds connection-related data such as type and credentials.
|
||||
* `currency`: 'EUR' | 'USD' – Currency of the account.
|
||||
* `name`: string – Name of the account.
|
||||
* `checkpoints`: object – Monthly checkpoint data structured by year.
|
||||
|
||||
#### ICsvDescriptor Interface
|
||||
The `ICsvDescriptor` interface describes a CSV file, consisting of:
|
||||
|
||||
* `name`: string – Name of the CSV file.
|
||||
* `contentString`: string – The content of the CSV file as a string.
|
||||
|
||||
### Abstract Class AcCsvParser
|
||||
The `AcCsvParser` abstract class serves as a blueprint for creating specific CSV parsers for different payment providers. It includes:
|
||||
|
||||
* `paymentProviderName`: Abstract property for the name of the payment provider.
|
||||
* `description`: Abstract property for a description of the parser.
|
||||
* `addCsvDecriptor`: Abstract method accepting a `ICsvDescriptor` object to process CSV data.
|
||||
* `getTransactions`: Abstract method returning a promise which resolves to an array of `IMonetaryTransaction` objects.
|
||||
|
||||
### Advanced Usage
|
||||
Beyond the basic usage demonstrated above, the `@fin.cx/portablefinance` package can be utilized for more advanced financial data management scenarios:
|
||||
|
||||
#### Handling Multiple CSV Files
|
||||
```typescript
|
||||
// Define multiple CSV descriptors
|
||||
const csvDescriptors: ICsvDescriptor[] = [
|
||||
{
|
||||
name: 'transactions_jan.csv',
|
||||
contentString: 'dummy content January', // Replace with actual content
|
||||
},
|
||||
{
|
||||
name: 'transactions_feb.csv',
|
||||
contentString: 'dummy content February', // Replace with actual content
|
||||
},
|
||||
];
|
||||
|
||||
// Add and parse all CSV files
|
||||
csvDescriptors.forEach((descriptor) => {
|
||||
csvParser.addCsvDecriptor(descriptor);
|
||||
});
|
||||
|
||||
// Retrieve and process all transactions
|
||||
const allTransactions = await csvParser.getTransactions();
|
||||
console.log('All Transactions:', allTransactions);
|
||||
```
|
||||
|
||||
#### Transaction Filtering and Aggregation
|
||||
```typescript
|
||||
// Filter transactions by date or amount
|
||||
const filteredTransactions = allTransactions.filter((transaction) => {
|
||||
return transaction.data.amount > 500; // Example: transactions greater than 500
|
||||
});
|
||||
|
||||
console.log('Filtered Transactions:', filteredTransactions);
|
||||
|
||||
// Aggregate transaction amounts
|
||||
const totalAmount = allTransactions.reduce((acc, transaction) => acc + transaction.data.amount, 0);
|
||||
console.log('Total Transaction Amount:', totalAmount);
|
||||
```
|
||||
|
||||
#### Integration with Payment Accounts
|
||||
```typescript
|
||||
// Assume we have multiple accounts
|
||||
const accounts: IPaymentAccount[] = [myAccount]; // Add more accounts as needed
|
||||
|
||||
// Link transactions to payment accounts
|
||||
const transactionsByAccount = accounts.map((account) => {
|
||||
return {
|
||||
accountId: account.id,
|
||||
transactions: allTransactions.filter((txn) => txn.data.paymentAccountId === account.id),
|
||||
};
|
||||
});
|
||||
|
||||
console.log('Transactions by Account:', transactionsByAccount);
|
||||
```
|
||||
|
||||
This comprehensive usage example covers the complete set of features provided by the `@fin.cx/portablefinance` package, demonstrating how to extend the abstract CSV parser, work with interfaces, handle multiple CSV files, filter and aggregate transactions, and integrate them with payment accounts. Feel free to customize the example based on your specific use cases and workflows.
|
||||
|
||||
For further information, consult the linked documentation at the top of this README.
|
||||
|
||||
Happy coding! 😊
|
||||
@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@fin.cx/portablefinance',
|
||||
version: '1.0.27',
|
||||
description: 'an interface package for the financeplus organization'
|
||||
version: '1.0.28',
|
||||
description: 'An interface package for handling financial transactions and account data within the financeplus organization.'
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user