futoin-xferengine

[![NPM Version](https://img.shields.io/npm/v/futoin-xferengine.svg?style=flat)](https://www.npmjs.com/package/futoin-xferengine) [![NPM Downloads](https://img.shields.io/npm/dm/futoin-xferengine.svg?style=flat)](https://www.npmjs.com/package/futoin-xferengine) [![Build Status](https://travis-ci.org/futoin/core-js-ri-xferengine.svg?branch=master)](https://travis-ci.org/futoin/core-js-ri-xferengine) [![stable](https://img.shields.io/badge/stability-stable-green.svg?style=flat)](https://www.npmjs.com/package/futoin-xferengine) [![NPM](https://nodei.co/npm/futoin-xferengine.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/futoin-xferengine/) # About **Work in progress. Technology preview, even though partially used in production.** Universal cluster focused transaction engine concept implementation. **Documentation** --> [FutoIn Guide](https://futoin.org/docs/xferengine/) Reference implementation of: FTN19: FutoIn Interface - Transaction Engine Version: 1.0 * Spec: [FTN19: FutoIn Interface - Transaction Engine v1.x](http://specs.futoin.org/draft/preview/ftn19_if_xfer_engine-1.html) ## Features: * Market cases (aka transaction domains): * Deposits & Withdrawals * Retail * Payments * Online Gaming * Fee bound to transaction (both deducted & extra) * Multi-currency * ISO fiat currencies * Crypto currency namespace * Any custom currency namespace * Advanced limits per transaction domain: * Per-account statistics * Daily, Weekly, Monthly limits for amounts & transaction count * Overdraft for balance * Dedicated "External" accounts for integration limits of third-party systems * Clustering with protocol level interaction * External Wallet (Seamless Wallet) * DB-based event stream for reliable state distribution for ad-hoc systems # Supported database types * MySQL * PostgreSQL * SQLite * Potentially, any other SQL-compliant supported by `futoin-database` # BIG FAT WARNING **Please DO NOT use it unless you really understand what it is. The package is published as essential open source part of derived custom closed source projects of different vendors.** # Installation for Node.js Command line: ```sh $ yarn add futoin-xferengine ``` or ```sh $ npm install futoin-xferengine --save ``` # Concept More detailed concept is in the FTN19 spec. # Examples ## 1. ```javascript ``` # API documentation The concept is described in FutoIn specification: [FTN19: FutoIn Interface - Transaction Engine v1.x](http://specs.futoin.org/draft/preview/ftn19_if_xfer_engine-1.html) ## Classes <dl> <dt><a href="#AccountsFace">AccountsFace</a></dt> <dd>Accounts Face </dd> <dt><a href="#AccountsService">AccountsService</a></dt> <dd>Accounts Service </dd> <dt><a href="#BaseFace">BaseFace</a></dt> <dd>Base Face with neutral common registration functionality </dd> <dt><a href="#BaseService">BaseService</a></dt> <dd>Base Service with common registration logic </dd> <dt><a href="#BonusFace">BonusFace</a></dt> <dd>Bonus Face </dd> <dt><a href="#BonusService">BonusService</a></dt> <dd>Bonus Service </dd> <dt><a href="#CachedAccountsFace">CachedAccountsFace</a></dt> <dd>Efficient cached AccountsFace with event-based cache invalidation Keeps local cache of limits and invalidates based on LIVE events. </dd> <dt><a href="#CachedLimitsFace">CachedLimitsFace</a></dt> <dd>Efficient cached LimitsFace with event-based cache invalidation Keeps local cache of limits and invalidates based on LIVE events. </dd> <dt><a href="#DepositFace">DepositFace</a></dt> <dd>Deposits Face </dd> <dt><a href="#DepositService">DepositService</a></dt> <dd>Deposits Service </dd> <dt><a href="#DepositTools">DepositTools</a></dt> <dd>XferTools with focus on Deposits use case </dd> <dt><a href="#GamingFace">GamingFace</a></dt> <dd>Gaming Face </dd> <dt><a href="#GamingService">GamingService</a></dt> <dd>Gaming Service </dd> <dt><a href="#GamingTools">GamingTools</a></dt> <dd>XferTools with focus on Gaming use case </dd> <dt><a href="#GenericFace">GenericFace</a></dt> <dd>Generic Face </dd> <dt><a href="#GenericService">GenericService</a></dt> <dd>Generic Service </dd> <dt><a href="#LimitsFace">LimitsFace</a></dt> <dd>Limits Face </dd> <dt><a href="#LimitsService">LimitsService</a></dt> <dd>Limits Service </dd> <dt><a href="#MessageFace">MessageFace</a></dt> <dd>Message Face </dd> <dt><a href="#MessageService">MessageService</a></dt> <dd>Message Service </dd> <dt><a href="#MessageTools">MessageTools</a></dt> <dd>XferTools with focus on Message processing </dd> <dt><a href="#PaymentFace">PaymentFace</a></dt> <dd>Payments Face </dd> <dt><a href="#PaymentService">PaymentService</a></dt> <dd>Payments Service </dd> <dt><a href="#PaymentTools">PaymentTools</a></dt> <dd>XferTools with focus on Payments use case </dd> <dt><a href="#PeerFace">PeerFace</a></dt> <dd>Peer Face </dd> <dt><a href="#PeerService">PeerService</a></dt> <dd>Peer Service </dd> <dt><a href="#RetailFace">RetailFace</a></dt> <dd>Payments Face </dd> <dt><a href="#RetailService">RetailService</a></dt> <dd>Retail Service </dd> <dt><a href="#RetailTools">RetailTools</a></dt> <dd>XferTools with focus on Retail use case </dd> <dt><a href="#UUIDTool">UUIDTool</a></dt> <dd>Extended UUIDTool with focus on collision safety in whole history of particular instance. </dd> <dt><a href="#WithdrawFace">WithdrawFace</a></dt> <dd>Witdrawals Face </dd> <dt><a href="#WithdrawService">WithdrawService</a></dt> <dd>Withdrawals Service </dd> <dt><a href="#XferCCM">XferCCM</a></dt> <dd>Special CCM implementation for XferCore </dd> <dt><a href="#CurrencyCacheInfoFace">CurrencyCacheInfoFace</a></dt> <dd>An efficient version of Currency/InfoFace. Keeps local cache of currencies and exchange rates. Listens on related event stream for changes as LIVE component. </dd> <dt><a href="#CurrencyInfoFace">CurrencyInfoFace</a></dt> <dd>Currency Information Face </dd> <dt><a href="#CurrencyInfoService">CurrencyInfoService</a></dt> <dd>Currency Manage Service </dd> <dt><a href="#CurrencyManageFace">CurrencyManageFace</a></dt> <dd>Currency Management Face </dd> <dt><a href="#CurrencyManageService">CurrencyManageService</a></dt> <dd>Currency Manage Service </dd> </dl> <a name="AccountsFace"></a> ## AccountsFace Accounts Face **Kind**: global class <a name="AccountsService"></a> ## AccountsService Accounts Service **Kind**: global class <a name="BaseFace"></a> ## BaseFace Base Face with neutral common registration functionality **Kind**: global class **Note**: Not official API * [BaseFace](#BaseFace) * [.LATEST_VERSION](#BaseFace.LATEST_VERSION) * [.PING_VERSION](#BaseFace.PING_VERSION) * [.register(as, ccm, name, endpoint, [credentials], [options])](#BaseFace.register) <a name="BaseFace.LATEST_VERSION"></a> ### BaseFace.LATEST\_VERSION Latest supported FTN17 version **Kind**: static property of [<code>BaseFace</code>](#BaseFace) <a name="BaseFace.PING_VERSION"></a> ### BaseFace.PING\_VERSION Latest supported FTN4 version **Kind**: static property of [<code>BaseFace</code>](#BaseFace) <a name="BaseFace.register"></a> ### BaseFace.register(as, ccm, name, endpoint, [credentials], [options]) CCM registration helper **Kind**: static method of [<code>BaseFace</code>](#BaseFace) | Param | Type | Default | Description | | --- | --- | --- | --- | | as | <code>AsyncSteps</code> | | steps interface | | ccm | <code>AdvancedCCM</code> | | CCM instance | | name | <code>string</code> | | CCM registration name | | endpoint | <code>\*</code> | | see AdvancedCCM#register | | [credentials] | <code>\*</code> | <code></code> | see AdvancedCCM#register | | [options] | <code>object</code> | <code>{}</code> | interface options | | [options.version] | <code>string</code> | <code>"1.0"</code> | interface version to use | <a name="BaseService"></a> ## BaseService Base Service with common registration logic **Kind**: global class * [BaseService](#BaseService) * _instance_ * [._checkType(type, val)](#BaseService+_checkType) ⇒ <code>boolean</code> * _static_ * [.register(as, executor, options)](#BaseService.register) ⇒ [<code>LimitsService</code>](#LimitsService) <a name="BaseService+_checkType"></a> ### baseService.\_checkType(type, val) ⇒ <code>boolean</code> Check value against type in spec of implemented interface **Kind**: instance method of [<code>BaseService</code>](#BaseService) **Returns**: <code>boolean</code> - result of check | Param | Type | Description | | --- | --- | --- | | type | <code>string</code> | name of defined type | | val | <code>\*</code> | value to check | <a name="BaseService.register"></a> ### BaseService.register(as, executor, options) ⇒ [<code>LimitsService</code>](#LimitsService) Register futoin.xfers.limits interface with Executor **Kind**: static method of [<code>BaseService</code>](#BaseService) **Returns**: [<code>LimitsService</code>](#LimitsService) - instance | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | steps interface | | executor | <code>Executor</code> | executor instance | | options | <code>object</code> | implementation defined options | <a name="BonusFace"></a> ## BonusFace Bonus Face **Kind**: global class <a name="BonusService"></a> ## BonusService Bonus Service **Kind**: global class <a name="CachedAccountsFace"></a> ## CachedAccountsFace Efficient cached AccountsFace with event-based cache invalidation Keeps local cache of limits and invalidates based on LIVE events. **Kind**: global class <a name="CachedAccountsFace.register"></a> ### CachedAccountsFace.register(as, ccm, name, endpoint, [credentials], [options]) CCM registration helper **Kind**: static method of [<code>CachedAccountsFace</code>](#CachedAccountsFace) | Param | Type | Default | Description | | --- | --- | --- | --- | | as | <code>AsyncSteps</code> | | steps interface | | ccm | <code>AdvancedCCM</code> | | CCM instance | | name | <code>string</code> | | CCM registration name | | endpoint | <code>\*</code> | | see AdvancedCCM#register | | [credentials] | <code>\*</code> | <code></code> | see AdvancedCCM#register | | [options] | <code>object</code> | <code>{}</code> | interface options | | [options.version] | <code>string</code> | <code>"<latest>"</code> | interface version to use | <a name="CachedLimitsFace"></a> ## CachedLimitsFace Efficient cached LimitsFace with event-based cache invalidation Keeps local cache of limits and invalidates based on LIVE events. **Kind**: global class <a name="CachedLimitsFace.register"></a> ### CachedLimitsFace.register(as, ccm, name, endpoint, [credentials], [options]) CCM registration helper **Kind**: static method of [<code>CachedLimitsFace</code>](#CachedLimitsFace) | Param | Type | Default | Description | | --- | --- | --- | --- | | as | <code>AsyncSteps</code> | | steps interface | | ccm | <code>AdvancedCCM</code> | | CCM instance | | name | <code>string</code> | | CCM registration name | | endpoint | <code>\*</code> | | see AdvancedCCM#register | | [credentials] | <code>\*</code> | <code></code> | see AdvancedCCM#register | | [options] | <code>object</code> | <code>{}</code> | interface options | | [options.version] | <code>string</code> | <code>"<latest>"</code> | interface version to use | <a name="DepositFace"></a> ## DepositFace Deposits Face **Kind**: global class <a name="DepositService"></a> ## DepositService Deposits Service **Kind**: global class <a name="DepositTools"></a> ## DepositTools XferTools with focus on Deposits use case **Kind**: global class <a name="GamingFace"></a> ## GamingFace Gaming Face **Kind**: global class <a name="GamingService"></a> ## GamingService Gaming Service **Kind**: global class <a name="GamingTools"></a> ## GamingTools XferTools with focus on Gaming use case **Kind**: global class <a name="GenericFace"></a> ## GenericFace Generic Face **Kind**: global class <a name="GenericService"></a> ## GenericService Generic Service **Kind**: global class <a name="LimitsFace"></a> ## LimitsFace Limits Face **Kind**: global class <a name="LimitsService"></a> ## LimitsService Limits Service **Kind**: global class <a name="MessageFace"></a> ## MessageFace Message Face **Kind**: global class <a name="MessageService"></a> ## MessageService Message Service **Kind**: global class <a name="MessageTools"></a> ## MessageTools XferTools with focus on Message processing **Kind**: global class <a name="PaymentFace"></a> ## PaymentFace Payments Face **Kind**: global class <a name="PaymentService"></a> ## PaymentService Payments Service **Kind**: global class <a name="PaymentTools"></a> ## PaymentTools XferTools with focus on Payments use case **Kind**: global class <a name="PeerFace"></a> ## PeerFace Peer Face **Kind**: global class <a name="PeerService"></a> ## PeerService Peer Service **Kind**: global class <a name="RetailFace"></a> ## RetailFace Payments Face **Kind**: global class <a name="RetailService"></a> ## RetailService Retail Service **Kind**: global class <a name="RetailTools"></a> ## RetailTools XferTools with focus on Retail use case **Kind**: global class <a name="UUIDTool"></a> ## UUIDTool Extended UUIDTool with focus on collision safety in whole history of particular instance. **Kind**: global class * [UUIDTool](#UUIDTool) * [.addXfer(xfer, val)](#UUIDTool.addXfer) * [.genXfer(xfer)](#UUIDTool.genXfer) ⇒ <code>string</code> <a name="UUIDTool.addXfer"></a> ### UUIDTool.addXfer(xfer, val) Call on xfer to ensure whole history uniqueness (just in case) **Kind**: static method of [<code>UUIDTool</code>](#UUIDTool) | Param | Type | Description | | --- | --- | --- | | xfer | <code>XferBuilder</code> | xfer builder object | | val | <code>string</code> | UUID in Base64 format without padding | <a name="UUIDTool.genXfer"></a> ### UUIDTool.genXfer(xfer) ⇒ <code>string</code> Generate UUID v4 in scope of transaction **Kind**: static method of [<code>UUIDTool</code>](#UUIDTool) **Returns**: <code>string</code> - UUID encoded in Base64 without padding | Param | Type | Description | | --- | --- | --- | | xfer | <code>XferBuilder</code> | xfer builder object | <a name="WithdrawFace"></a> ## WithdrawFace Witdrawals Face **Kind**: global class <a name="WithdrawService"></a> ## WithdrawService Withdrawals Service **Kind**: global class <a name="XferCCM"></a> ## XferCCM Special CCM implementation for XferCore **Kind**: global class * [XferCCM](#XferCCM) * [.registerServices(as, executor)](#XferCCM+registerServices) * [.registerEventServices(as, executor)](#XferCCM+registerEventServices) * [.registerCurrencyServices(as, executor)](#XferCCM+registerCurrencyServices) * [.registerLimitServices(as, executor)](#XferCCM+registerLimitServices) * [.registerAccountServices(as, executor)](#XferCCM+registerAccountServices) * [.makeManualAlias(iface, key)](#XferCCM+makeManualAlias) ⇒ <code>string</code> * [.registerOnDemand(iface, flavour, callback)](#XferCCM+registerOnDemand) * [.xferIface(as, iface, account)](#XferCCM+xferIface) <a name="XferCCM+registerServices"></a> ### xferCCM.registerServices(as, executor) Register all services required for operation **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | async step interface | | executor | <code>Executor</code> | internal protected executor | <a name="XferCCM+registerEventServices"></a> ### xferCCM.registerEventServices(as, executor) Register event services required for operation **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | async step interface | | executor | <code>Executor</code> | internal protected executor | <a name="XferCCM+registerCurrencyServices"></a> ### xferCCM.registerCurrencyServices(as, executor) Register currency services required for operation **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | async step interface | | executor | <code>Executor</code> | internal protected executor | <a name="XferCCM+registerLimitServices"></a> ### xferCCM.registerLimitServices(as, executor) Register limit services required for operation **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | async step interface | | executor | <code>Executor</code> | internal protected executor | <a name="XferCCM+registerAccountServices"></a> ### xferCCM.registerAccountServices(as, executor) Register account services required for operation **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | async step interface | | executor | <code>Executor</code> | internal protected executor | <a name="XferCCM+makeManualAlias"></a> ### xferCCM.makeManualAlias(iface, key) ⇒ <code>string</code> Get manual alias for specific iface & key combination **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) **Returns**: <code>string</code> - - manual key to be used with registerOnDemand() | Param | Type | Description | | --- | --- | --- | | iface | <code>string</code> | interface identifier | | key | <code>string</code> | arbitrary key, typically account # | <a name="XferCCM+registerOnDemand"></a> ### xferCCM.registerOnDemand(iface, flavour, callback) Register callback for on-demand interface creation **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | iface | <code>string</code> | full iface identifier | | flavour | <code>string</code> | a type of interface implementation | | callback | <code>callable</code> | callback to register interface | <a name="XferCCM+xferIface"></a> ### xferCCM.xferIface(as, iface, account) Get interface with on-demand logic **Kind**: instance method of [<code>XferCCM</code>](#XferCCM) | Param | Type | Description | | --- | --- | --- | | as | <code>AsyncSteps</code> | async step interface | | iface | <code>string</code> | full iface identifier | | account | <code>string</code> | related account ID | <a name="CurrencyCacheInfoFace"></a> ## CurrencyCacheInfoFace An efficient version of Currency/InfoFace. Keeps local cache of currencies and exchange rates. Listens on related event stream for changes as LIVE component. **Kind**: global class <a name="CurrencyCacheInfoFace.register"></a> ### CurrencyCacheInfoFace.register(as, ccm, name, endpoint, [credentials], [options]) CCM registration helper **Kind**: static method of [<code>CurrencyCacheInfoFace</code>](#CurrencyCacheInfoFace) | Param | Type | Default | Description | | --- | --- | --- | --- | | as | <code>AsyncSteps</code> | | steps interface | | ccm | <code>AdvancedCCM</code> | | CCM instance | | name | <code>string</code> | | CCM registration name | | endpoint | <code>\*</code> | | see AdvancedCCM#register | | [credentials] | <code>\*</code> | <code></code> | see AdvancedCCM#register | | [options] | <code>object</code> | <code>{}</code> | interface options | | [options.version] | <code>string</code> | <code>"<latest>"</code> | interface version to use | <a name="CurrencyInfoFace"></a> ## CurrencyInfoFace Currency Information Face **Kind**: global class <a name="CurrencyInfoService"></a> ## CurrencyInfoService Currency Manage Service **Kind**: global class <a name="CurrencyManageFace"></a> ## CurrencyManageFace Currency Management Face **Kind**: global class <a name="CurrencyManageService"></a> ## CurrencyManageService Currency Manage Service **Kind**: global class *documented by [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown)*.