DVM Request

The DVM Request module provides utilities for making requests to Data Vending Machines (DVMs) and handling their responses. It includes support for progress tracking and result handling.

Core Types

DVMRequestOptions

type DVMRequestOptions = {
  event: SignedEvent       // The event to send to the DVM
  relays: string[]        // Relays to use
  timeout?: number        // Request timeout in milliseconds
  autoClose?: boolean     // Auto-close subscription after result
  reportProgress?: boolean // Listen for progress events
}

DVMEvent Enum

enum DVMEvent {
  Progress = "progress", // DVM progress updates (kind 7000)
  Result = "result"     // Final DVM result
}

Making DVM Requests

Basic Usage

import { makeDvmRequest, DVMEvent } from '@welshman/dvm'

const request = makeDvmRequest({
  event: signedEvent,
  relays: ["wss://relay.example.com"],
  timeout: 30000, // 30 seconds
})

// Handle results
request.emitter.on(DVMEvent.Result, (url, event) => {
  console.log('Received result:', event)
})

// Handle progress updates
request.emitter.on(DVMEvent.Progress, (url, event) => {
  console.log('Progress update:', event)
})

Response Handling

Result Events

request.emitter.on(DVMEvent.Result, (url: string, event: TrustedEvent) => {
  // Handle the DVM result
  const result = JSON.parse(event.content)

  // Process tags
  const requestTag = event.tags.find(t => t[0] === 'request')
  const expirationTag = event.tags.find(t => t[0] === 'expiration')
})

Progress Updates

request.emitter.on(DVMEvent.Progress, (url: string, event: TrustedEvent) => {
  // Handle progress update (kind 7000)
  const progress = JSON.parse(event.content)
  console.log(`Progress: ${progress.percentage}%`)
})

Complete Example

import { makeDvmRequest, DVMEvent } from '@welshman/dvm'
import { createEvent, finalizeEvent } from '@welshman/util'

async function queryDVM() {
  // Create the request event
  const event = createEvent(5001, {
    content: JSON.stringify({
      query: "search terms"
    })
  })

  // Sign the event
  const signedEvent = finalizeEvent(event, privateKey)

  // Make the request
  const dvmRequest = makeDvmRequest({
    event: signedEvent,
    relays: ["wss://relay.example.com"],
    timeout: 30000,
    reportProgress: true
  })

  // Handle progress updates
  dvmRequest.emitter.on(DVMEvent.Progress, (url, event) => {
    console.log('Progress:', event.content)
  })

  // Return a promise that resolves with the result
  return new Promise((resolve, reject) => {
    const timeout = setTimeout(() => {
      dvmRequest.sub.close()
      reject(new Error('DVM request timeout'))
    }, 30000)

    dvmRequest.emitter.on(DVMEvent.Result, (url, event) => {
      clearTimeout(timeout)
      resolve(event)
    })
  })
}

This module simplifies the process of making requests to DVMs while providing flexibility in handling responses and progress updates.