npm package: @lokavaluto/lokapi-backend-comchain
Description: Comchain backend for Lokavaluto API
Author: Valentin LAB
Latest version: 0.1.1-alpha.202603170757



This is a backend for managing any comchain currency through LokAPI.
The latter aims at providing a simple framework for building client
app to manage currency payments. You can refer to
`@lokavaluto/lokapi`'s doc to get more knowledge of how to use it.

# Adding `@lokavaluto/lokapi-backend-comchain` to your project

From the root of your project:

```sh
npm install --save @lokavaluto/lokapi-backend-comchain
```

Or better, as `@lokavaluto/lokapi-backend-comchain` is still in early release,

```sh
npm install --save Lokavaluto/lokapi-backend-comchain#master
```

To be sure to get the latest version, relaunch this last command
whenever you want to update.


# Usage

You can provide this backend when subclassing LokAPI:

For instance:

```typescript
import LokAPIBrowserAbstract from "@lokavaluto/lokapi-browser"

import comchain from '@lokavaluto/lokapi-backend-comchain'

class LokAPI extends LokAPIBrowserAbstract {

  BackendFactories = {
    comchain,
  }

  requestLocalPassword = async function (state: string) {
    // ... your UI code to request password from user
  }

  requestLogin() {
    // ... your UI code to request password from user
  }

}

if (!process.env.VUE_APP_LOKAPI_HOST) {
  throw new Error("Please specify VUE_APP_LOKAPI_HOST in '.env'")
}

if (!process.env.VUE_APP_LOKAPI_DB) {
  throw new Error("Please specify VUE_APP_LOKAPI_DB in '.env'")
}

export var lokAPI = new LokAPI(
  process.env.VUE_APP_LOKAPI_HOST,
  process.env.VUE_APP_LOKAPI_DB,
)
```


For usage of `@lokavaluto/lokapi`, please refer to
`@lokavaluto/lokapi`'s documentation.

# Developers

To get started developing and tinkering with this code, you can:

## Install dependencies

```sh
npm install
```

## Build the project

```sh
npx tsc -w
```

## Launch tests

Tests are managed through `vitest`

```sh
## Run test once
npm run test
```

Note that you can also use `npx vitest` command to launch tests in
watch mode.
# Changelog


## 0.1.1-alpha.202603170757

### New

* Validate wallet currency before registration. [Valentin Lab]

  Check that the wallet's ``server.name`` matches the backend's
  currency before proceeding with registration. Throws
  ``CurrencyMismatch`` if they differ, avoiding unnecessary
  Odoo calls.

* Throw ``CurrencyNotAvailable`` on wallet currency mismatch. [Valentin Lab]

  Detect when the Odoo registration error mentions the wallet's
  currency name and "not found", and throw a typed exception
  instead of a generic ``Error``.

* Add ``Recipient.preparePledge(..)`` [Valentin Lab]

* Add ``Recipient.updateAccount(..)`` [Valentin Lab]

* Add ``Backend.getUserAccountsFromWalletIdent()`` [Valentin Lab]

* Add ``Backend.getCurrencyName()`` [Valentin Lab]

* Add ``UserAccount.getCurrencySupply()`` [Valentin Lab]

* Add ``Backend.isUnconfiguredBackend()`` [Seddik]

* Use currency's technical accounts to determine top-up and reconversion. [Valentin Lab]

* Support new ``Recipient.isTransferAllowedByAdministrativeBackend()`` [Valentin Lab]

* Support mutual currency. [Valentin Lab]

* Add ``{UserAccount,Account,Recipient}.isBusinessForFinanceBackend(..)`` [Valentin Lab]

* ``transaction.isReconversion`` property now return string state also. [Valentin Lab]

  If false, it is not a reconversion, if true it is a reconversion but wasn't
  yet acknowledged by the administrative backend. If it is a string, then it
  is the state as defined by the administrative backend.

* Add ``transaction.isReconversion`` property. [Valentin Lab]

* Add ``transaction.isTopUp`` property. [Seddik Kadi]

* Use bigint for amount to prevent any quirks in balances result. [Valentin Lab]

* Update to use financial backend's ``Backend.activateAccount(..)`` [Valentin Lab]

* Add check of transaction id format on ``recipient.transfer(..)`` [Valentin Lab]

* Make ``{User,}Account.getBalance()`` to specify a block point as first argument. [Seddik]

* Add ``Recipient.discardCreateRequest()`` [Seddik Kadi]

* Add ``Backend.registerWallet()`` to register a new wallet. [Seddik Kadi]

* Provide ``UserAccount.getPendingTopUp()`` for convenience. [Valentin Lab]

* Use new base ``Account`` provided by ``lokapi`` [Valentin Lab]

### Changes

* Rename validation rights methods to financial scope. [Valentin Lab]

* Split description into ```senderMemo``` and ```recipientMemo``` [Seddik]

* Make ``Recipient.transfer()`` return a full ``Transaction`` object. [Valentin Lab]

### Fix

* Ensure compatibility with mutual credit only currencies. [Valentin Lab]

* Repair possible issues with ``jsc3l`` complaining about unconfigured objects. [Valentin Lab]

  The issue was in the cache implementation.

* Make reconversion status code compatible with financial backend not implementing the API ``/recipients`` endpoint. [Valentin Lab]

* Ensure sane defaults of ``limitMin`` and ``limitMax`` of mutual credit allowances. [Valentin Lab]

* Block credit requests of amounts above safe f64 representation. [Valentin Lab]

  Here we block above 2**46 because we'd like to ensure full
  representation of all 99 cents of a unit. Real integer limit is
  number.MAX_SAFE_INTEGER (2**53 - 1).

* Allow reloading ``getCurrencyMgr`` on failure only. [Valentin Lab]

* Improve error reporting on common mis-configuration. [Valentin Lab]

* Add retry mechanism for fetching transaction info. [Seddik]

* Move misplaced ``console.log`` [Valentin Lab]

* Compatibility with latest ``credit-request`` API endpoint. [Valentin Lab]

  Value is not anymore a string representing a date, but a timestamp. As
  a consequence we get a full date and time information for pending
  top-up requests.

* Maintain compatibility with new ``jsc3l`` throwing real ``Error`` [Valentin Lab]


## 0.1.0 (2023-05-08)

### New

* Add ``Transaction.pending`` implementation. [Valentin Lab]

* Add compatibility with new smartcontract with pledge and property admin. [Valentin Lab]

* Add date filter to ``getTransactions(..)`` [Valentin Lab]

* Update odoo API calls from ``comchain/partners`` to ``comchain/contact`` [Valentin Lab]

* Add ``Recipient.getSymbol()`` method implementation. [Valentin Lab]

* Add ``Recipient.fromUserAccount`` property. [Valentin Lab]

* Add ``UserAccount.requestCredentials(..)`` to check credentials and return them. [Valentin Lab]

  Note that ``UserAccount.unlockWallet(..)`` and
  ``UserAccount.requestCredentials(..)`` can both provide their override
  of the general ``.requestLocalPassword`` method.

* Provide ``UserAccount.requiresUnlock()`` to advertise if an unlock is required on current ``userAccount`` [Valentin Lab]

* Make ``Backend.createUserAccount(..)`` return a ``UserAccount`` [Valentin Lab]

* Single out insufficient balance error to throw common exception. [Seddik Kadi]

* Throw exception upon transfer of invalid amounts. [Valentin Lab]

* Add ``.makeCreditRequest(..)`` on backend and user account. [Valentin Lab]

* Add ``.isActiveAccount()`` on user account. [Valentin Lab]

* Add ``.creditable`` property on money account. [Valentin Lab]

* Add ``.hasCreditRequestValidationRights()`` [Valentin Lab]

* Add ``.validateCreation()`` on recipient. [Valentin Lab]

* Catch and properly throw ``InactiveAccount`` when account seems locked. [Valentin Lab]

* Add ``.hasUserAccountValidationRights()`` support. [Valentin Lab]

* Add ``createUserAccount(..)`` [Valentin Lab]

* Inactive user account don't have any money account accessible. [Valentin Lab]

* User accounts can now act as money accounts containing other accounts. [Valentin Lab]

  In comchain we want a global account view and 2 sub accounts, so
  we can exploit this new feature.

* Bank account provide a ``type`` property. [Valentin Lab]

  ``type`` property can return string "Nant" or "Cm". These are the
  two bank account type that can be attached to a comchain wallet.

* Api v12 changed structure of backend data ``bank_accounts`` -> ``accounts`` [Valentin Lab]

* ``Backend.internalId`` is now provided by super class. [Valentin Lab]

### Changes

* Remove API point ``{creditRequest,Transacion}.relatedUser`` [Valentin Lab]

  Was not bringing anything more than already existing API point
  ``related``.

### Fix

* Make validated account standard user. [Valentin Lab]

  It doesn't change anything in current contract but costs less
  for the smart-contract and is probably a better default value
  for most current users.

* Return source user for incoming transaction. [Valentin Lab]

  Prior to this fix, current user was returned.

* Correct ``.getCreditUrl()`` from bogus behavior due to copy-paste typo. [Valentin Lab]

* Prevent exception coming from deciphering transaction memo to break and provide sane default. [Valentin Lab]

* Correctly provide the currency for each ``type`` of account. [Valentin Lab]

* Don't try to uncipher transaction messages if no message key is available. [Valentin Lab]

* Use account hex address in transaction if not found in administrative backend. [Valentin Lab]


## 0.0.1 (2021-11-17)

### Other

* First import. [Valentin Lab]