npm package: @minka/ledger-sdk
Description: SDK for Minka Ledger
Author: Željko Rumenjak
Latest version: 2.39.0

# Minka Ledger SDK

An SDK for interacting with the Minka Ledger.

## Getting started

### Installation

Install this package by running:

```
npm install @minka/ledger-sdk
```

### Basic usage

First, you need an instance of the `LedgerSDK` class, you can pass an options object with the `required` property `server` pointing to the ledger you want to use.

```javascript
const ledger = new LedgerSdk({
  server: 'https://minka.inc..',
})
```

That ledger instance has different **Clients** and only one `status` method that returns the status of the ledger.

**Note:** Most of the methods in the entire SDK are `asynchronous`, meaning they return a promise you need to wait to be resolved by using `async/`await`(preferred) functions or `.then()` at the end of the methods chain.

&nbsp;&nbsp;

#### Clients

Each entity of the ledger has its client, and those clients are properties of the `LedgerSDK` instance, for example, the client for `signer` will be returned in `sdk.signer` if you used the example below to connect to the ledger.

Available clients: `ledger`, `symbol`, `wallet`, `intent`, `signer`, `effect` and `bridge`.

##### Common client methods

All clients have common methods for listing (`list`), fetching (`read`) and initializing (`init`) entities

###### list

The `list` method allows you to fetch a list of the required entity, it has an optional object of type `LedgerListParams` as a param to pass pagination and filtering options to it. You can read more about it [here](#link-to-list-docs)

```javascript
const output = await sdk.signer.list()
// output: MultipleRecordsResponse
```

###### read

The `read` method allows you to fetch a single record of the required entity, it has a required string param that is the handle you want to fetch.

```javascript
const output = await sdk.signer.read('handle')
// output: SingleRecordResponse
```

###### drop

The `drop` method allows you to delete a single record of the required entity. There are two ways of doing so:

- Passing a string param that is the handle/luid you want to delete. Internally fetches the record to obtain its hash before proceeding with the drop request.

```javascript
// Initialize a drop record builder for the wallet entity
// Call .hash() to create a new record hash
// Call .sign() to add a signature
const dropWalletRecord = await sdk.wallet.drop('handle').hash().sign([{ keyPair }])
/**
 * Send the DELETE request to the backend.
 */
const response = await dropWalletRecord.send()
```

- Passing the ledger record you want to delete, in cases where you have fetched it before.

```javascript
const fetchedWallet: LedgerRecord<LedgerWallet> = {
  hash: '<hash>',
  data: {
    handle: '<wallet-handle>',
    access: [
      {
        action: '<action>',
        signer: {
          public: '<public-key>',
        },
      },
    ],
  },
  luid: '<luid>',
  meta: {
    proofs: [
      {
        custom: {
          moment: '<moment>',
          status: '<status>',
        },
        digest: '<digest>',
        method: '<method>',
        public: '<public-key>',
        result: '<result>',
      },
    ],
    status: '<status>',
    moment: '<moment>',
    owners: ['<owner>'],
  },
}

// Initialize a drop record builder for the wallet
const dropWalletRecord = await sdk.wallet
  .drop(record)
  .hash()
  .sign([{ keyPair: yourKeyPair }])

/**
 * Send the DELETE request to the backend.
 * Optionally, you can pass authParams and headers to the send method.
 */
const response = await dropWalletRecord.send({ authParams, headers })
```

###### init

the `init` method allows you to initialize a new `record builder` instance. `record builders` provide a more convenient way to work with the records by implementing methods to hash, sign, test and send them to the ledger. You can optionally pass the initial record to the init method, otherwise, it will be initialized with an empty record.

```javascript
// Initialize a record builder for the signer entity
const emptySignerRecord = await sdk.signer.init()
/**
 * Send that record to the backend. Note this record will
 * return error because it's empty.
 */
const response = await emptySignerRecord.send()
```

Keep in mind that methods are chainable, so you can easily create a record as follows;

```javascript
/**
 * "{}" represents valid data for the record
 * "keyPair" represents a valid key pair
 */
await sdk.signer.init({}).hash().sign([{ keyPair }]).send()
```