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:

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:

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:

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:

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:

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:

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.