mirror of
https://github.com/nbd-wtf/nostr-tools.git
synced 2025-12-09 00:28:51 +00:00
112 lines
3.4 KiB
Markdown
112 lines
3.4 KiB
Markdown
# nostr-tools
|
|
|
|
Tools for developing [Nostr](https://github.com/fiatjaf/nostr) clients.
|
|
|
|
## Usage
|
|
|
|
```js
|
|
import {relayPool} from 'nostr-tools'
|
|
|
|
const pool = relayPool()
|
|
|
|
pool.setPrivateKey('<hex>') // optional
|
|
|
|
pool.addRelay('ws://some.relay.com', {read: true, write: true})
|
|
pool.addRelay('ws://other.relay.cool', {read: true, write: true})
|
|
|
|
// example callback functions for listeners
|
|
// callback functions take an object argument with following keys:
|
|
// - relay: relay url
|
|
// - type: type of listener
|
|
// - id: sub id for sub specific listeners ('EVENT' or 'EOSE')
|
|
// - event: event object, only for 'event' listener
|
|
// - notice: notice message, only for 'notice' listener
|
|
function onEvent({event, relay, type, id}) {
|
|
console.log(`got an event from ${relay} which is already validated.`, event)
|
|
}
|
|
function onEose({relay, type, id}) { /* callback function here */}
|
|
function onNotice({relay, type, notice}) { /* callback function here */}
|
|
function onConnection({relay, type}) { /* callback function here */}
|
|
|
|
// listen for messages for pool
|
|
pool.on('event', onEvent)
|
|
pool.on('connection', onConnection)
|
|
pool.on('notice', onNotice)
|
|
|
|
// subscribing to a single user
|
|
// author is the user's public key
|
|
pool.sub({filter: {author: '<hex>'}})
|
|
|
|
// or bulk follow
|
|
pool.sub({filter: {authors: ['<hex1>', '<hex2>', ..., '<hexn>']}})
|
|
|
|
// reuse a subscription channel
|
|
const mySubscription = pool.sub({filter: ...., skipVerification: false, beforeSend: ....})
|
|
mySubscription.sub({filter: ....})
|
|
mySubscription.sub({skipVerification: true})
|
|
|
|
// listen for messages for subscription
|
|
mySubscription.on('event', onEvent)
|
|
mySubscription.on('eose', onEose)
|
|
|
|
// close subscription
|
|
mySubscription.unsub()
|
|
|
|
// get specific event
|
|
const specificChannel = pool.sub({ filter: {id: '<hex>'}})
|
|
.on('event', ({event, relay}) => {
|
|
console.log('got specific event from relay', event, relay)
|
|
specificChannel.unsub()
|
|
})
|
|
|
|
// or get a specific event plus all the events that reference it in the 'e' tag
|
|
pool.sub({ filter: [{id: '<hex>'}, {'#e': '<hex>'}] })
|
|
|
|
// get all events
|
|
pool.sub({ filter: {} })
|
|
|
|
// get recent events
|
|
pool.sub({ filter: {since: timestamp} })
|
|
|
|
// publishing events(inside an async function):
|
|
const ev = await pool.publish(eventObject, (status, url) => {
|
|
if (status === 0) {
|
|
console.log(`publish request sent to ${url}`)
|
|
}
|
|
if (status === 1) {
|
|
console.log(`event published by ${url}`, ev)
|
|
}
|
|
})
|
|
// it will be signed automatically with the key supplied above
|
|
// or pass an already signed event to bypass this
|
|
|
|
// subscribing to a new relay
|
|
pool.addRelay('<url>')
|
|
// will automatically subscribe to the all the events called with .sub above
|
|
```
|
|
|
|
All functions expect bytearrays as hex strings and output bytearrays as hex strings.
|
|
|
|
For other utils please read the source (for now).
|
|
|
|
### Using from the browser (if you don't want to use a bundler)
|
|
|
|
You can import nostr-tools as an ES module. Just add a script tag like this:
|
|
|
|
```html
|
|
<script type="module">
|
|
import {generatePrivateKey} from 'https://unpkg.com/nostr-tools/nostr.js'
|
|
console.log(generatePrivateKey())
|
|
</script>
|
|
```
|
|
|
|
And import whatever function you would import from `"nostr-tools"` in a bundler.
|
|
|
|
## TypeScript
|
|
|
|
This module has hand-authored TypeScript declarations. `npm run check-ts` will run a lint-check script to ensure the typings can be loaded and call at least a few standard library functions. It's not at all comprehensive and likely to contain bugs. Issues welcome; tag @rcoder as needed.
|
|
|
|
## License
|
|
|
|
Public domain.
|