nostr-reqres

The NostrReqRes library is a JavaScript library that provides an easy way to create, manage, and track request/response communication of any size over Nostr protocol. By automatically splitting and reassembling large payloads into smaller chunks, it allows seamless handling of requests and responses without size limitations. The library utilizes Nostr Tools for low-level operations and implements higher-level abstractions for request and response handling.

Installation

npm install @nostr-connect/nostr-reqres

Examples

// Import the NostrReqRes module
import { NostrReqRes } from "@nostr-connect/nostr-reqres"

// Define an immediately invoked async function expression (IIFE)
void (async () => {
  // Create new instances of NostrReqRes for the sender and the receiver
  const nostrReqResSENDER = new NostrReqRes()
  const nostrReqResRECEIVER = new NostrReqRes()

  // Connect both sender and receiver to the WebSocket server at localhost:7001
  await Promise.all([
    nostrReqResSENDER.connect("ws://localhost:7001"),
    nostrReqResRECEIVER.connect("ws://localhost:7001")
  ])

  // Set up an event listener for incoming requests on the receiver
  nostrReqResRECEIVER.onReqReceived(async (req) => {
    // Log the request data to the console
    console.log(req.data) // ping

    // Send a response with the data "pong" back to the sender
    await req.sendRes({
      data: "pong"
    })
  })

  // Send a request from the sender to the receiver with the data "ping"
  const res = await nostrReqResSENDER.sendReq({
    receiver: nostrReqResRECEIVER.pubkey,
    data: "ping"
  })

  // Log the response data to the console
  console.log(res.data) // pong
})()
  // Catch any errors and log them to the console
  .catch((err) => {
    console.error(err)
  })

// Import the NostrReqRes library
import { NostrReqRes } from "@nostr-connect/nostr-reqres";

// Create an immediately invoked async function expression
void (async () => {
  // Initialize sender and receiver instances of NostrReqRes
  const nostrReqResSENDER = new NostrReqRes();
  const nostrReqResRECEIVER = new NostrReqRes();

  // Connect both sender and receiver to the WebSocket server at localhost on port 7001
  await Promise.all([
    nostrReqResSENDER.connect("ws://localhost:7001"),
    nostrReqResRECEIVER.connect("ws://localhost:7001")
  ]);

  // Set up an event listener for when the receiver receives a request chunk
  nostrReqResRECEIVER.onReq(async (req) => {
    // Log received request chunks
    req.onChunk((chunk) => {
      console.log("req chunk received", chunk);
    });

    // Set up an event listener for when the entire request is received
    req.onReceived(async (req) => {
      // Log the received request data
      console.log(req.data); // "ping"

      // Create a response object with the data "pong"
      const res = req.createRes({
        data: "pong"
      });

      // Send the response back to the sender
      await res.send();
    });
  });

  // Create a new request object with the receiver's public key and the data "ping"
  const req = await nostrReqResSENDER.createReq({
    receiver: nostrReqResRECEIVER.pubkey,
    data: "ping"
  });

  // Log sent request chunks
  req.onChunk((chunk) => {
    console.log("req chunk sent", chunk);
  });

  // Send the request and wait for the response
  const res = await req.send();

  // Log the received response data
  console.log(res.data); // "pong"
})()
  .catch((err) => {
    // Log any errors that occur during execution
    console.error(err);
  });

NostrReqRes constuctor options

• kind (optional, number): The kind of event to be used for request-response communication. Default is 28080.
• maxBytesPerChunk (optional, number): The maximum number of bytes allowed per chunk when splitting large payloads. Default is NostrReqRes.MAX_BYTES_PER_CHUNK (16384).
• secretKey (optional, string): The secret key to be used for signing and encrypting events. Default is a randomly generated private key.
• validateEventsSig (optional, boolean): A flag indicating whether to validate event signatures when receivd; this shuold be done by the relay. Default is false.
• waitForRealyAckWhenSendingChunks (optional, boolean): A flag indicating whether to wait for a relay acknowledgement when sending chunks; not all the relay implements the ack on ephimeral kinds. Default is false.

example:

import { NostrReqRes } from "@nostr-connect/nostr-reqres";

const nostrReqRes = new NostrReqRes({
  kind: 28080,
  maxBytesPerChunk: 1000,
  secretKey: "your_secret_key",
  validateEventsSig: false,
  waitForRealyAckWhenSendingChunks: true
});