# smart-widget-handler

A lightweight JavaScript/TypeScript library for facilitating communication between a host application and a client widget, with support for Nostr account metadata and event handling via `window.postMessage`. Ideal for building smart widgets that interact with Nostr-based ecosystems.

## Installation

Install the package via npm:

```bash
npm install smart-widget-handler
```

## Usage

The library provides two main interfaces: host for the parent application and client for the embedded widget. Import the default export SWHandler to send and receive messages between contexts.

Example: Host Sending and Listening
Send a connected Nostr account to a widget and listen for messages from the widget:

```js
import SWHandler from "smart-widget-handler";

// Listen for messages from the widget
let listener = SWHandler.host.listen((data) => {
  console.log("Received from widget:", data.kind, data.data);
  if (data.kind === "custom-data") {
    console.log("Custom data:", data.data);
  }
});

// To close the listener
listener.close()

// Send user context to the widget
const context = {
    pubkey: "npub1example...",
    display_name: "string",
    name: "string",
    picture: "string",
    nip05: "string",
    lud16: "string",
    lud06: "string",
    website: "string",
};
let host_origin: "https://myapp.com";

SWHandler.host.sendContext(context, host_origin, "https://widget.example.com", <YOUR_IFRAME_ELEMENT>);
```

### Example: Client Sending and Listening

---

Notify the host that the widget is ready, listen for messages, and send custom data:

```js
import SWHandler from "smart-widget-handler";

// Notify host that widget is loaded
SWHandler.client.ready();

// Listen for messages from the host
let listener = SWHandler.client.listen((data) => {
  console.log("Received from host:", data.kind, data.data);
  if (data.kind === "user-metadata") {
    const { display_name } = data.data;
    console.log(`Hello, ${display_name}!`);
  }
});

// To close the listener
listener.close();

// Send custom data to the host
SWHandler.client.sendContext("User clicked a button", "https://myapp.com");
```

### Example: Client Requesting Event Signing

Request the host to sign a Nostr event:

```js
import SWHandler from "smart-widget-handler";

const event = {
  content: "Hello, Nostr!",
  tags: [["t", "greeting"]],
  kind: 1,
};

SWHandler.client.requestEventSign(event, "https://myapp.com");
```

---

### Example: Client Requesting Payment

Request the host to initiate a Lightning payment:

```js
import SWHandler from "smart-widget-handler";

const paymentRequest = {
  address: "lnbc1...", // or LNURL, or Lightning address
  amount: 1000, // sats (ignored if address is a BOLT11 invoice)
  nostrPubkey: "npub1example...", // optional
  nostrEventIDEncode: "note1example...", // optional
};

SWHandler.client.requestPayment(paymentRequest, "https://myapp.com");
```

---

### Example: Host Sending Payment Response

Send a payment response from the host to the client:

```js
import SWHandler from "smart-widget-handler";

const paymentResponse = {
  status: true, // true for success, false for error
  preImage: "abcdef123456...", // optional, only for successful payments
};

SWHandler.host.sendPaymentResponse(paymentResponse, "https://widget.example.com", <YOUR_IFRAME_ELEMENT>);
```

## Message Types

The library uses different message types identified by the `data.kind` property to handle various communication scenarios between host and client. Here's a comprehensive list of all available message types:

| Message Type | Direction | Description |
|-------------|-----------|-------------|
| `user-metadata` | Host → Client | Contains Nostr account information of the connected user |
| `nostr-event` | Host → Client | Contains a signed and/or published Nostr event |
| `err-msg` | Host → Client | Contains an error message from the host |
| `payment-response` | Host → Client | Contains the result of a payment request (success/failure) |
| `app-loaded` | Client → Host | Notifies the host that the client widget is loaded and ready |
| `sign-event` | Client → Host | Requests the host to sign a Nostr event |
| `sign-publish` | Client → Host | Requests the host to sign and publish a Nostr event |
| `payment-request` | Client → Host | Requests the host to make a Lightning payment |
| `custom-data` | Client → Host | Contains custom data sent from the client to the host |

When implementing listeners with `SWHandler.host.listen()` or `SWHandler.client.listen()`, you can filter and handle these message types based on your application's needs.