# alby-tools

> Collection of helpful building blocks and tools to develop Bitcoin Lightning web apps

Latest version **3.2.1** (published 2023-07-26) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install alby-tools
pnpm add alby-tools
yarn add alby-tools
bun add alby-tools
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.2.1 |
| Published | 2023-07-26 |
| First published | 2022-10-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 2 |
| Unpacked size | 283.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 49 |
| Author | Alby contributors |
| Maintainers | bumi |
| Keywords | lightning, bitcoin, alby |

## Links

- npm: https://www.npmjs.com/package/alby-tools
- Repository: https://github.com/getAlby/alby-tools
- Issues: https://github.com/getAlby/alby-tools/issues
- Funding: lightning:hello@getalby.com
- npm.io page: https://npm.io/package/alby-tools

## Dependencies (2)

- [crypto-js](https://npm.io/package/crypto-js.md) ^4.1.1
- [light-bolt11-decoder](https://npm.io/package/light-bolt11-decoder.md) ^3.0.0

## Recent versions

- 3.2.1 (latest) — 2023-07-26
- 3.2.0 — 2023-07-13
- 3.1.3 — 2023-07-13
- 3.1.2 — 2023-07-12
- 3.1.1 — 2023-07-12
- 3.1.0 — 2023-07-11
- 3.0.0 — 2023-06-04
- 2.3.0 — 2023-05-05
- 2.2.1 — 2023-05-03
- 2.2.0 — 2023-04-23
- 2.1.2 — 2023-04-20
- 2.1.1 — 2023-04-17
- 2.1.0 — 2023-03-28
- 2.0.0 — 2023-03-22
- 1.3.0 — 2023-03-15
- … 5 more at https://npm.io/package/alby-tools/versions

## README

<p align="center">
  <img width="100%" src="https://github.com/getAlby/alby-tools/raw/master/docs/Header.png">
</p>

# Lightning Web SDK

An npm package that provides useful and common tools and helpers to build lightning web applications.

## 🚀 Quick Start

```
npm install alby-tools
```
or
```
yarn add alby-tools
```
or for use without any build tools:
```
// alby-tools now available at window.albyTools
<script src="https://cdn.jsdelivr.net/npm/alby-tools@3.0.0/dist/index.browser.js"></script>
```

**This library relies on a global `fetch()` function which will work in [browsers](https://caniuse.com/?search=fetch) and node v18 or newer.** (In older versions you have to use a polyfill.)

## 🤙 Usage

### Lightning Address

The `LightningAddress` class provides helpers to work with lightning addresses

```js
import { LightningAddress } from "alby-tools";

const ln = new LightningAddress("hello@getalby.com");

// fetch the LNURL data
await ln.fetch();

// get the LNURL-pay data:
console.log(ln.lnurlpData); // returns a [LNURLPayResponse](https://github.com/getAlby/alby-tools/blob/master/src/types.ts#L1-L15)
// get the keysend data:
console.log(ln.keysendData);

```

#### Get an invoice:

```js
import { LightningAddress } from "alby-tools";

const ln = new LightningAddress("hello@getalby.com");

await ln.fetch();
// request an invoice for 1000 satoshis
// this returns a new `Invoice` class that can also be used to validate the payment
const invoice = await ln.requestInvoice({satoshi: 1000});

console.log(invoice.paymentRequest); // print the payment request
console.log(invoice.paymentHash); // print the payment hash
```

#### Verify a payment

```js
import { LightningAddress } from "alby-tools";
const ln = new LightningAddress("hello@getalby.com");
await ln.fetch();

const invoice = await ln.requestInvoice({satoshi: 1000});

// if the LNURL providers supports LNURL-verify:
const paid = await invoice.verifyPayment(); // returns true of false
if (paid) {
  console.log(invoice.preimage);
}

// if you have the preimage for example in a WebLN context
await window.webln.enable();
const response = await window.webln.sendPayment(invoice.paymentRequest);
const paid = invoice.validatePreimage(response.preimage); // returns true or false
if (paid) {
  console.log('paid');
}

// or use the convenenice method:
await invoice.isPaid();

```

It is also possible to manually initialize the `Invoice`

```js
const { Invoice } = require("alby-tools");

const invoice = new Invoice({paymentRequest: pr, preimage: preimage});
await invoice.isPaid();
```

#### Boost a LN address:

You can also attach additional metadata information like app name, version, name of the podcast which is boosted etc. to the keysend payment.

```js
import { LightningAddress } from "alby-tools";
const ln = new LightningAddress("hello@getalby.com");
await ln.fetch();

const boost = {
  action: "boost",
  value_msat: 21000,
  value_msat_total: 21000,
  app_name: "Podcastr",
  app_version: "v2.1",
  feedId: "21",
  podcast: "random podcast",
  episode: "1",
  ts: 2121,
  name: "Satoshi",
  sender_name: "Alby",
}
await ln.boost(boost);
```

#### Zapping a LN address on Nostr:

Nostr is a simple, open protocol that enables truly censorship-resistant and global value-for-value publishing on the web. Nostr integrates deeply with Lightning. [more info](https://nostr.how/)

alby-tools provides helpers to create [zaps](https://github.com/nostr-protocol/nips/blob/master/57.md).

```js
import { LightningAddress } from "alby-tools";
const ln = new LightningAddress("hello@getalby.com");
await ln.fetch();

const response = await ln.zap({
  satoshi: 1000,
  comment: "Awesome post",
  relays: ["wss://relay.damus.io"],
  e: "44e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245"
});
console.log(response.preimage); // print the preimage
```

For a full example see [examples/zaps](examples/zaps.js)

#### Zapping a LN address on Nostr using Nostr Wallet Connect:

Native zaps without a browser extension are possible by using a Nostr Wallet Connect WebLN provider.

See [examples/zaps-nwc](examples/zaps-nwc.js)

### L402

L402 is a protocol standard based on the HTTP 402 Payment Required error code
designed to support the use case of charging for services and
authenticating users in distributed networks.

alby-tools includes a `fetchWithL402` function to consume L402 protected resources.

#### fetchWithL402(url: string, fetchArgs, options)

+ url: the L402 protected URL
+ fetchArgs: arguments are passed to the underlaying `fetch()` function used to do the HTTP request
+ options:
  + webln: the webln object used to call `sendPayment()` defaults to globalThis.webln
  + store: a key/value store object to persiste the l402 for each URL. The store must implement a `getItem()`/`setItem()` function as the browser's localStorage. By default a memory storage is used.
  + headerKey: defaults to L402 but if you need to consume an old LSAT API set this to LSAT

##### Examples

```js
import { fetchWithL402 } from "alby-tools";

// this will fetch the resouce and pay the invoice with window.webln.
// the tokens/preimage data will be stored in the browser's localStorage and used for any following request
await fetchWithL402('https://lsat-weather-api.getalby.repl.co/kigali', {}, { store: window.localStorage }).then(res => res.json()).then(console.log)
```

```js
import { fetchWithL402 } from "alby-tools";
import { webln } from "alby-js-sdk";

// use a NWC WebLN provide to do the payments
const nwc = new webln.NostrWebLNProvider({ nostrWalletConnectUrl: loadNWCUrl() });

// this will fetch the resouce and pay the invoice with a NWC webln object
await fetchWithL402('https://lsat-weather-api.getalby.repl.co/kigali', {}, { webln: nwc }).then(res => res.json()).then(console.log)
```

```js
import { l402 } from "alby-tools";

// do not store the tokens
await l402.fetchWithL402('https://lsat-weather-api.getalby.repl.co/kigali', {}, { store: new l402.storage.NoStorage() })
``

### 💵 Fiat conversions
Helpers to convert sats values to fiat and fiat values to sats.

##### getFiatValue(satoshi: number, currency: string): number
Returns the fiat value for a specified currrency of a satoshi amount

##### getSatoshiValue(amount: number, currency: string): number
Returns the satoshi value for a specified amount (in the smallest denomination) and currency

##### getFormattedFiatValue(satoshi: number, currency: string, locale: string): string
Like `getFiatValue` but returns a formatted string for a given locale using JavaScript's `toLocaleString`

#### Examples

```js
await getFiatValue(satoshi: 2100, currency: 'eur');
await getSatoshiValue(amount: 100, currency: 'eur'); // for 1 EUR
await getFormattedFiatValue(stoshi: 2100, currency: 'usd', locale: 'en')
```

### 🤖 Lightning Address Proxy
alby-tools uses a [proxy](https://github.com/getAlby/lightning-address-details-proxy) to simplify requests to lightning providers.

- Many ln addresses don't support CORS, which means fetching the data directly in a browser environment will not always work.
- Two requests are required to retrieve lnurlp and keysend data for a lightning address. The proxy will do these for you with a single request.

You can disable the proxy by explicitly setting the proxy to false when initializing a lightning address:

```
const lightningAddress = new LightningAddress("hello@getalby.com", {proxy: false});
```

## fetch() dependency
This library relies on a global fetch object which will work in browsers and node v18.x or newer. In old version yoi can manually install a global fetch option or polyfill if needed.

For example:
```js
import fetch from "cross-fetch"; // or "@inrupt/universal-fetch"
globalThis.fetch = fetch;

// or as a polyfill:
import 'cross-fetch/polyfill';
```

## 🛠 Development

```
yarn install
yarn run build
```

## Need help?

We are happy to help, please contact us or create an issue.

* [Twitter: @getAlby](https://twitter.com/getAlby)
* [Telegram group](https://t.me/getAlby)
* support at getalby.com
* [bitcoin.design](https://bitcoin.design/) Discord community (find us on the #alby channel)
* Read the [Alby developer guide](https://guides.getalby.com/overall-guide/alby-for-developers/getting-started) to better understand how Alby packages and APIs can be used to power your app.

## License

MIT

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