Add vitepress docs
This commit is contained in:
Ticruz
Jon Staab
@@ -0,0 +1,107 @@
|
||||
# DVM (Data Vending Machine) Handler
|
||||
|
||||
The DVM Handler module provides a framework for creating and managing Data Vending Machines in the Nostr ecosystem.
|
||||
A DVM is a service that listens for specific kinds of events and responds with processed data.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### DVM Handler
|
||||
```typescript
|
||||
type DVMHandler = {
|
||||
stop?: () => void
|
||||
handleEvent: (e: TrustedEvent) => AsyncGenerator<StampedEvent>
|
||||
}
|
||||
```
|
||||
A handler defines how to process specific kinds of events and generate responses.
|
||||
|
||||
### DVM Options
|
||||
```typescript
|
||||
type DVMOpts = {
|
||||
sk: string // Private key for signing responses
|
||||
relays: string[] // Relays to connect to
|
||||
handlers: Record<string, CreateDVMHandler> // Event handlers by kind
|
||||
expireAfter?: number // Response expiration time in seconds
|
||||
requireMention?: boolean // Require DVM to be mentioned in event
|
||||
}
|
||||
```
|
||||
|
||||
## Creating a DVM
|
||||
|
||||
```typescript
|
||||
import { DVM } from '@welshman/dvm'
|
||||
|
||||
// Create handlers for different event kinds
|
||||
const handlers = {
|
||||
// Handler for kind 5001
|
||||
"5001": (dvm: DVM) => ({
|
||||
handleEvent: async function*(event: TrustedEvent) {
|
||||
// Process event and yield responses
|
||||
yield {
|
||||
kind: 6001,
|
||||
content: "Processed result",
|
||||
created_at: now(),
|
||||
tags: []
|
||||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// Initialize DVM
|
||||
const dvm = new DVM({
|
||||
sk: "your-private-key",
|
||||
relays: ["wss://relay.example.com"],
|
||||
handlers,
|
||||
expireAfter: 3600, // 1 hour
|
||||
requireMention: true
|
||||
})
|
||||
|
||||
// Start the DVM
|
||||
await dvm.start()
|
||||
```
|
||||
|
||||
|
||||
## Example Implementation
|
||||
|
||||
```typescript
|
||||
import { DVM, CreateDVMHandler } from '@welshman/dvm'
|
||||
import { now } from '@welshman/lib'
|
||||
|
||||
// Create a search handler
|
||||
const createSearchHandler: CreateDVMHandler = (dvm) => ({
|
||||
handleEvent: async function*(event) {
|
||||
const query = event.content
|
||||
const results = await performSearch(query)
|
||||
|
||||
yield {
|
||||
kind: 6001,
|
||||
content: JSON.stringify(results),
|
||||
created_at: now(),
|
||||
tags: [
|
||||
["search", query],
|
||||
["results", String(results.length)]
|
||||
]
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
// Initialize DVM
|
||||
const searchDVM = new DVM({
|
||||
sk: process.env.DVM_KEY!,
|
||||
relays: ["wss://relay1.com", "wss://relay2.com"],
|
||||
handlers: {
|
||||
"5001": createSearchHandler
|
||||
},
|
||||
expireAfter: 24 * 60 * 60, // 24 hours
|
||||
requireMention: true
|
||||
})
|
||||
|
||||
// Start DVM
|
||||
await searchDVM.start()
|
||||
|
||||
// Stop DVM when needed
|
||||
process.on('SIGINT', () => {
|
||||
searchDVM.stop()
|
||||
})
|
||||
```
|
||||
|
||||
The DVM Handler provides a robust foundation for building Nostr data services, with built-in support for common requirements like deduplication, response signing, and metadata management.
|
||||
@@ -0,0 +1,18 @@
|
||||
# @welshman/dvm
|
||||
|
||||
`@welshman/dvm` is a comprehensive package for building and interacting with Data Vending Machines (DVMs) in the Nostr ecosystem. It provides both server-side DVM implementation capabilities and client-side request handling.
|
||||
|
||||
## What is a DVM?
|
||||
|
||||
A Data Vending Machine (DVM) is a Nostr service that:
|
||||
- Listens for specific kinds of events
|
||||
- Processes these events according to defined rules
|
||||
- Responds with new events containing processed data
|
||||
- Optionally provides progress updates during processing
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @welshman/dvm
|
||||
```
|
||||
@@ -0,0 +1,119 @@
|
||||
# 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
|
||||
```typescript
|
||||
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
|
||||
```typescript
|
||||
enum DVMEvent {
|
||||
Progress = "progress", // DVM progress updates (kind 7000)
|
||||
Result = "result" // Final DVM result
|
||||
}
|
||||
```
|
||||
|
||||
## Making DVM Requests
|
||||
|
||||
### Basic Usage
|
||||
```typescript
|
||||
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
|
||||
```typescript
|
||||
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
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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.
|
||||
Reference in New Issue
Block a user