nostr

README

go-nostr

go-nostr is a package that provides a simple interface to access nostr relay servers.

Installation

go get -u github.com/shota3506/go-nostr

Documentation

Index

• type Client
  • func NewClient(url string) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Publish(ctx context.Context, event *Event) (*CommandResult, error)
  • func (c *Client) Subscribe(ctx context.Context, filters []Filter) (*Subscription, error)
• type CloseMessage
  • func (m *CloseMessage) MarshalJSON() ([]byte, error)
• type CommandResult
• type EOSEMessage
• type Event
  • func (e *Event) Sign(privKey string) error
• type EventKind
• type EventMessage
  • func (m *EventMessage) MarshalJSON() ([]byte, error)
• type Filter
• type MessageType
• type NoticeMessage
• type OKMessage
• type ReqMessage
  • func (m *ReqMessage) MarshalJSON() ([]byte, error)
• type Subscription
  • func (s *Subscription) ID() string
  • func (s *Subscription) Receive(ctx context.Context, f func(context.Context, *Event)) error
• type Tag

Examples

• Client.Publish
• Client.Subscribe

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client is a Nostr client that connects to a relay server.

func NewClient

func NewClient(url string) (*Client, error)

NewClient creates a new Nostr client. It establishes a websocket connection to the relay server.

func (*Client) Close

func (c *Client) Close() error

Close closes the client connection.

func (*Client) Publish

func (c *Client) Publish(ctx context.Context, event *Event) (*CommandResult, error)

Publish submits an event to the relay server and waits for the command result.

Example

package main

import (
	"context"
	"time"

	"github.com/shota3506/go-nostr"
)

func main() {
	client, err := nostr.NewClient("URL") // TODO: Replace URL with a relay server URL.
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()

	event := &nostr.Event{
		CreatedAt: time.Now().Unix(),
		Kind:      nostr.EventKindTextNote,
		Content:   "Hello, World!",
		Tags:      []nostr.Tag{},
	}
	event.Sign("PRIVATE_KEY") // TODO: Replace PRIVATE_KEY with your private key.

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	result, err := client.Publish(ctx, event)
	if err != nil {
		// TODO: Handle error.
	}

	_ = result // TODO: Check result.
}

func (*Client) Subscribe

func (c *Client) Subscribe(ctx context.Context, filters []Filter) (*Subscription, error)

Subscribe creates a subscription to the relay server with the given filters.

Example

package main

import (
	"context"
	"time"

	"github.com/shota3506/go-nostr"
)

func main() {
	client, err := nostr.NewClient("URL") // TODO: Replace URL with a relay server URL.
	if err != nil {
		// TODO: Handle error.
	}
	defer client.Close()

	ctx := context.Background()
	sub, err := client.Subscribe(ctx, []nostr.Filter{{}})
	if err != nil {
		// TODO: Handle error.
	}

	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	err = sub.Receive(ctx, func(ctx context.Context, event *nostr.Event) {
		// TODO: Do something with event.
	})
}

type CloseMessage

type CloseMessage struct {
	SubscriptionID string
}

A CloseMessage is a close message. It's used to stop previous subscriptions.

func (*CloseMessage) MarshalJSON

func (m *CloseMessage) MarshalJSON() ([]byte, error)

type CommandResult

type CommandResult struct {
	OK      bool
	Message string
}

A CommandResult is a result of a command.

type EOSEMessage

type EOSEMessage struct {
	SubscriptionID string
}

A EOSEMessage is a EOSE message. It's used to notify clients all stored events have been sent.

type Event

type Event struct {
	ID        string    `json:"id"`
	PubKey    string    `json:"pubkey"`
	CreatedAt int64     `json:"created_at"`
	Kind      EventKind `json:"kind"`
	Tags      []Tag     `json:"tags"`
	Content   string    `json:"content"`
	Sig       string    `json:"sig"`
}

Event is an Nostr event.

func (*Event) Sign

func (e *Event) Sign(privKey string) error

Sing signs the event with the given private key. It sets the ID, PubKey, and Sig fields.

type EventKind

type EventKind int64

EventKind is the kind of an event.

const (
	EventKindSetMetadata             EventKind = 0    // NIP-01
	EventKindTextNote                EventKind = 1    // NIP-01
	EventKindRecommendServer         EventKind = 2    // NIP-01
	EventKindContacts                EventKind = 3    // NIP-02
	EventKindEncryptedDirectMessages EventKind = 4    // NIP-04
	EventKindEventDeletion           EventKind = 5    // NIP-09
	EventKindReposts                 EventKind = 6    // NIP-18
	EventKindReaction                EventKind = 7    // NIP-25
	EventKindBadgeAward              EventKind = 8    // NIP-58
	EventKindChannelCreation         EventKind = 40   // NIP-28
	EventKindChannelMetadata         EventKind = 41   // NIP-28
	EventKindChannelMessage          EventKind = 42   // NIP-28
	EventKindChannelHideMessage      EventKind = 43   // NIP-28
	EventKindChannelMuteUser         EventKind = 44   // NIP-28
	EventKindFileMetadata            EventKind = 1063 // NIP-94
	EventKindReporting               EventKind = 1984 // NIP-56
	EventKindZapRequest              EventKind = 9734 // NIP-57
	EventKindZap                     EventKind = 9735 // NIP-57
)

type EventMessage

type EventMessage struct {
	SubscriptionID string // optional
	Event          *Event
}

A EventMessagek is an event message. It's used to publish events from clients or to send events requested to clients

func (*EventMessage) MarshalJSON

func (m *EventMessage) MarshalJSON() ([]byte, error)

type Filter

type Filter struct {
	IDs     []string    `json:"ids,omitempty"`
	Kinds   []EventKind `json:"kinds,omitempty"`
	Authors []string    `json:"authors,omitempty"`
	Tags    []Tag       `json:"-,omitempty"`
	Since   int64       `json:"since,omitempty"` // TODO: use box type
	Until   int64       `json:"until,omitempty"` // TODO: use box type
	Limit   int         `json:"limit,omitempty"`
	Search  string      `json:"search,omitempty"`
}

A Filter is a filter for subscription.

type MessageType

type MessageType string

MessageType is the type of a message.

const (
	MessageTypeEvent  MessageType = "EVENT"  // NIP-01
	MessageTypeReq    MessageType = "REQ"    // NIP-01
	MessageTypeClose  MessageType = "CLOSE"  // NIP-01
	MessageTypeNotice MessageType = "NOTICE" // NIP-01
	MessageTypeEOSE   MessageType = "EOSE"   // NIP-01
	MessageTypeOK     MessageType = "OK"     // NIP-20
)

type NoticeMessage

type NoticeMessage struct {
	Message string
}

A NoticeMessage is a notice message. It's used to send human-readable messages to clients.

type OKMessage

type OKMessage struct {
	EventID string
	OK      bool
	Message string
}

A OKMessage is a OK message. It's used to notify clients if an EVENT was successful.

type ReqMessage

type ReqMessage struct {
	SubscriptionID string
	Filters        []Filter
}

A ReqMessage is a request message. It's used to request events and subscribe to new updates.

func (*ReqMessage) MarshalJSON

func (m *ReqMessage) MarshalJSON() ([]byte, error)

type Subscription

type Subscription struct {
	// contains filtered or unexported fields
}

A Subscription is a subscription to a channel.

func (*Subscription) ID

func (s *Subscription) ID() string

ID returns the subscription ID.

func (*Subscription) Receive

func (s *Subscription) Receive(ctx context.Context, f func(context.Context, *Event)) error

Receive calls f for each event received from the subscription. If ctx is done, Receive returns nil.

The context passed to f will be canceled when ctx is Done or there is a fatal service error.

type Tag

type Tag []string

Tag is a tag of an event.