# dero-xswd-api

> JS/TS api for the XSWD protocol on the DERO wallet

Latest version **0.8.3-d** (published 2024-03-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install dero-xswd-api
pnpm add dero-xswd-api
yarn add dero-xswd-api
bun add dero-xswd-api
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.8.3-d |
| Published | 2024-03-13 |
| First published | 2023-12-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 173.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | bisounours |
| Maintainers | dabisounours |
| Keywords | dero, xswd, api, ts, js |

## Links

- npm: https://www.npmjs.com/package/dero-xswd-api
- Repository: https://github.com/dero-community/xswd-api
- Homepage: https://github.com/dero-community/xswd-api#readme
- Issues: https://github.com/dero-community/xswd-api/issues
- npm.io page: https://npm.io/package/dero-xswd-api

## Dependencies (2)

- [@types/node](https://npm.io/package/@types/node.md) ^20.9.0
- [@lesomnus/channel](https://npm.io/package/@lesomnus/channel.md) ^0.0.1

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.8.3-d (latest) — 2024-03-13
- 0.7.0-a (beta) — 2024-01-13
- 0.8.3-c — 2024-03-13
- 0.8.3-b — 2024-02-16
- 0.8.3 — 2024-02-15
- 0.8.2 — 2024-02-01
- 0.8.1 — 2024-01-31
- 0.8.0 — 2024-01-20
- 0.7.3-b — 2024-01-14
- 0.7.3-a — 2024-01-14
- 0.7.3 — 2024-01-14
- 0.7.2 — 2024-01-14
- 0.7.1 — 2024-01-13
- 0.7.0 — 2024-01-13
- 0.6.3 — 2024-01-11
- … 6 more at https://npm.io/package/dero-xswd-api/versions

## README

# DERO XSWD Web API
Disclaimer: Be aware that this API is still under development and might change.
## Getting started

### Install

```sh
# Using npm
npm install dero-xswd-api
```
```sh
# Using yarn
yarn add dero-xswd-api
```

### Usage
#### Initialisation
##### Typescript
```ts
import { Api, AppInfo, generateAppId } from "dero-xswd-api";

// Define a name
const name = "My application";

// Fill up some info, these fields must be non-empty
const appInfo: AppInfo = {
  id: generateAppId(name), // generates a hash automatically
  name,
  description: "My app's description",
  url: "https://myapp.com" // Optional
};

// Create the api object
const xswd = new Api(appInfo);

// Initialize the connection => Will require to confirm in your wallet
await xswd.initializeXSWD();
```
##### Javascript
```js
import { Api, generateAppId } from "dero-xswd-api";

const name = "My application";

const appInfo = {
  id: generateAppId(name),
  name,
  description: "My app's description",
  url: "https://myapp.com" // Optional
};

const xswd = new Api(appInfo);

await xswd.initializeXSWD();
```

#### Using custom configuration and fallback node connection

```ts
// Refer to Config type in "src/types/types.ts"
const config /*: Config */= {
  address: "127.0.0.1",
  port: 40000, // example for simulator wallet using xswd
  secure: false, // uses "wss://" prefix (secure websocket) when true. Useful to connect to a remote node under an "https://" scheme.
  debug: true, // debug mode enabled. will print a lot of messages to console.
};

// fallback should point to a node so that blockchain data or SC data can be pulled even if the wallet is not connected
const fallback_config /*: Config */ = { 
  address: "127.0.0.1",
  port: 20000, // example for simulator node
  secure: false, 
  // debug attribute here will be ignored
}
      
const xswd = new Api(appInfo, config, fallback_config);

await xswd.initializeFallback();
await xswd.initializeXSWD(); // if this one succeeds, the fallback connection will be closed.

```

#### Handle closing websocket

If the websocket connection is closed, the `onclose` callback will be called.

```js
// set a handler for the websocket closing
xswd.onclose = function(connectionType/* : ConnectionType */, closeEvent /* : CloseEvent */) {
  if (connectionType == "xswd" /* connectionType == ConnectionType.XSWD */) {
    console.error("Connection was closed!", closeEvent)
  }
}
```

#### Calls

For daemon calls use: `xswd.node.<command>`

For wallet calls use: `xswd.wallet.<command>`

>*Note:* calls like `xswd.wallet.transfer` & `xswd.wallet.scinvoke` should wait for a *new_entry* event after the call using the `xswd.waitFor` method (examples below).
>Also, the `xswd.node.GetSC` has an optional parameter in order to wait for a new block before it fetches the data (using `waitFor` underneath).

##### Example (Typescript)
```ts
import { to, Result } from "dero-xswd-api";

// call GetHeight method
const response = await xswd.node.GetHeight()

// handle response
if ('result' in response) {
  console.log(resultResponse.result.topoheight)
}
if ('error' in response) {
  console.error(response.error.message)
}

// or using the "to" function to get error and result separately
const [error, result] = 
  to<"daemon", "DERO.GetHeight", Result>(response);
if (result !== undefined) {
  console.log(result.topoheight)
}
```

check [tests](tests/index.test.ts) file for more examples.

#### Events

##### Subscribe to an event (Typescript)

```ts
import { EventType } from "dero-xswd-api";

// let the api subscribe to the event 
// "new_topoheight" | "new_balance" | "new_entry"
const eventType: EventType = "new_topoheight" 

await xswd.subscribe({
  event: "new_topoheight", // "new_topoheight" | "new_balance" | "new_entry"
});

// once subscribed you can wait for this event
await xswd.waitFor("new_balance")

// add a predicate
await xswd.waitFor("new_topoheight", 
  (new_height) => new_height > 2394
)

// you can add a callback to the subscription
await xswd.subscribe({
  event: "new_balance",
  callback: (balance) => {
    console.log(balance);
  },
});
```

# Roadmap

- [x] base protocol
- [x] fallback to public daemon if connection failed (by default, can be disabled)
- [x] implement GetTrackedAssets
- [ ] implement new node GetSC methods

---
_Source: https://npm.io/package/dero-xswd-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
