Documentation
¶
Index ¶
- func ClientConnectHandler(w http.ResponseWriter, r *http.Request)
- func ClientDisconnectHandler(w http.ResponseWriter, r *http.Request)
- func ClientRelaysHandler(w http.ResponseWriter, r *http.Request)
- func GetCacheHandler(w http.ResponseWriter, r *http.Request)
- func GetSessionHandler(w http.ResponseWriter, r *http.Request)
- func GetUserProfileHandler(w http.ResponseWriter, r *http.Request)
- func GetUserRelaysHandler(w http.ResponseWriter, r *http.Request)
- func HandleAmberCallback(w http.ResponseWriter, r *http.Request)
- func KeyDeriveHandler(w http.ResponseWriter, r *http.Request)
- func KeyGenerationHandler(w http.ResponseWriter, r *http.Request)
- func KeyValidationHandler(w http.ResponseWriter, r *http.Request)
- func LoginHandler(w http.ResponseWriter, r *http.Request)
- func LogoutHandler(w http.ResponseWriter, r *http.Request)
- func Nip19DecodeHandler(w http.ResponseWriter, r *http.Request)
- func PingHandler(w http.ResponseWriter, r *http.Request)
- func PrivateKeyConversionHandler(w http.ResponseWriter, r *http.Request)
- func PublicKeyConversionHandler(w http.ResponseWriter, r *http.Request)
- func PublishEventHandler(w http.ResponseWriter, r *http.Request)
- func QueryEventsHandler(w http.ResponseWriter, r *http.Request)
- func RefreshCacheHandler(w http.ResponseWriter, r *http.Request)
- type ClientRelaysResponse
- type KeyGenerationResponse
- type KeyValidationResponse
- type Nip19DecodeRequest
- type PublishEventRequest
- type PublishEventResponse
- type RelayStatus
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClientConnectHandler ¶ added in v0.4.12
func ClientConnectHandler(w http.ResponseWriter, r *http.Request)
ClientConnectHandler connects the client to a relay Usage: POST /api/v1/client/connect/relay.damus.io?read=true&write=false
@Summary Connect to a relay @Description Dials the relay (auto-detecting `ws://` vs `wss://`) and adds it to the logged-in user's managed relay list with the requested permissions. @Tags client-relays @Produce json @Param domain path string true "Relay domain (no scheme)" @Param read query bool false "Permission to subscribe from this relay (default true)" @Param write query bool false "Permission to publish to this relay (default true)" @Success 200 {object} map[string]interface{} @Failure 400 {object} map[string]interface{} "Missing domain or no permissions enabled" @Failure 401 {object} map[string]string "Login required" @Failure 405 {string} string "Method not allowed" @Failure 500 {object} map[string]interface{} "Connect failed" @Router /api/v1/client/connect/{domain} [post]
func ClientDisconnectHandler ¶ added in v0.4.12
func ClientDisconnectHandler(w http.ResponseWriter, r *http.Request)
ClientDisconnectHandler disconnects the client from a relay Usage: POST /api/v1/client/disconnect/relay.damus.io
@Summary Disconnect from a relay @Description Removes the relay from the logged-in user's managed list and closes the pooled WebSocket if one is open. @Tags client-relays @Produce json @Param domain path string true "Relay domain (no scheme)" @Success 200 {object} map[string]interface{} @Failure 400 {object} map[string]string "Missing domain" @Failure 401 {object} map[string]string "Login required" @Failure 404 {object} map[string]interface{} "Relay not in user's list" @Failure 405 {string} string "Method not allowed" @Failure 500 {object} map[string]interface{} "Disconnect failed" @Router /api/v1/client/disconnect/{domain} [post]
func ClientRelaysHandler ¶ added in v0.4.12
func ClientRelaysHandler(w http.ResponseWriter, r *http.Request)
ClientRelaysHandler returns the client's configured relays and their status Works with or without authentication - returns user relays if authenticated, app relays if not
@Summary List client relays @Description Returns the client's currently-configured relays with read/write permissions and live connection state. Falls back to the default index relays when no session is active. @Tags client-relays @Produce json @Param ping query string false "Set to `true` to measure latency for each relay" @Success 200 {object} ClientRelaysResponse @Failure 405 {string} string "Method not allowed" @Failure 500 {string} string "Failed to retrieve client relays" @Router /api/v1/client/relays [get]
func GetCacheHandler ¶ added in v0.4.1
func GetCacheHandler(w http.ResponseWriter, r *http.Request)
GetCacheHandler returns the cached user data as JSON (no session data) Automatically refreshes cache if expired or missing
@Summary Get cached user data @Description Returns the cached profile, mailboxes (kind 10002), and managed client relay list for the logged-in user. Rebuilds the cache on miss. @Tags client-cache @Produce json @Success 200 {object} map[string]interface{} @Failure 401 {string} string "User not logged in" @Failure 500 {string} string "Failed to load user data" @Router /api/v1/cache [get]
func GetSessionHandler ¶ added in v0.4.1
func GetSessionHandler(w http.ResponseWriter, r *http.Request)
GetSessionHandler returns the current user's session data as JSON (auth state only)
@Summary Get current session @Description Returns the logged-in user's pubkey, sign-in mode (read-only/write), and signing method. 401 if no active session. @Tags client-auth @Produce json @Success 200 {object} map[string]interface{} @Failure 401 {string} string "No active session found" @Router /api/v1/session [get]
func GetUserProfileHandler ¶ added in v0.4.1
func GetUserProfileHandler(w http.ResponseWriter, r *http.Request)
GetUserProfileHandler fetches user profile using core client
@Summary Get user profile @Description Fetches the kind-0 profile event for the given pubkey from outbox relays. Falls back to the logged-in user's pubkey if `pubkey` is omitted. @Tags client-events @Produce json @Param pubkey query string false "Hex pubkey (defaults to current session)" @Success 200 {object} map[string]interface{} @Failure 401 {string} string "Authentication required" @Failure 404 {string} string "Profile not found" @Failure 503 {string} string "No relay connections available" @Router /api/v1/user/profile [get]
func GetUserRelaysHandler ¶ added in v0.4.1
func GetUserRelaysHandler(w http.ResponseWriter, r *http.Request)
GetUserRelaysHandler fetches user relay list using core client
@Summary Get user relays @Description Fetches the kind-10002 relay list (mailboxes) for the given pubkey. Falls back to the logged-in user's pubkey if `pubkey` is omitted. @Tags client-events @Produce json @Param pubkey query string false "Hex pubkey (defaults to current session)" @Success 200 {object} map[string]interface{} @Failure 401 {string} string "Authentication required" @Failure 404 {string} string "Relays not found" @Failure 503 {string} string "No relay connections available" @Router /api/v1/user/relays [get]
func HandleAmberCallback ¶ added in v0.4.1
func HandleAmberCallback(w http.ResponseWriter, r *http.Request)
HandleAmberCallback is the redirect target for NIP-55 (Amber).
Mill's <nostr-signer> opens `nostrsigner://...?callbackUrl=...`; Amber bounces back with `?event=<pubkey-or-signed-event>&error=` on that URL. The page rendered here loads the bundled mill script so its boot-time hook (see nip55.js around line 17) captures the query params, stores them under `mill:amber:result` in localStorage, and notifies the opener window via postMessage. `MILL.deliverAmberCallback({autoClose:true})` finishes the handshake and closes the popup.
The server intentionally does NOT create the session here. The pubkey funnels back into mill in the opener window; the bridge (www/static/js/mill-bridge.js) is what POSTs /api/v1/auth/login with the resolved method and pubkey. Keeping session creation in one path (the bridge) means there's a single contract with the session manager regardless of signing method.
@Summary Amber NIP-55 callback @Description Landing page hit by the Amber signer app. Loads mill, which forwards the result to the opener window and closes the popup. Session creation lives in the front-end mill bridge, not here. @Tags client-auth @Param event query string false "Amber response: pubkey hex (get_public_key) or signed event JSON" @Param error query string false "Amber error message, if user rejected" @Produce html @Success 200 {string} string "HTML bridge page" @Router /api/v1/auth/amber-callback [get]
func KeyDeriveHandler ¶ added in v0.4.12
func KeyDeriveHandler(w http.ResponseWriter, r *http.Request)
KeyDeriveHandler derives public key from private key
@Summary Derive public key @Description Derives the pubkey (hex + npub) from a private key supplied in the URL path. Accepts either hex or nsec format. @Tags client-keys @Produce json @Param key path string true "Private key (hex or nsec)" @Success 200 {object} map[string]string @Failure 400 {object} map[string]string "Invalid key" @Failure 405 {string} string "Method not allowed" @Router /api/v1/keys/derive/{key} [get]
func KeyGenerationHandler ¶ added in v0.4.12
func KeyGenerationHandler(w http.ResponseWriter, r *http.Request)
KeyGenerationHandler generates a new random Nostr key pair
@Summary Generate keypair @Description Generates a fresh secp256k1 keypair and returns both the hex and bech32 (nsec/npub) forms. Pure utility — the relay does not store the private key. @Tags client-keys @Produce json @Success 200 {object} KeyGenerationResponse @Failure 405 {string} string "Method not allowed" @Failure 500 {object} KeyGenerationResponse "Key pair generation failed" @Router /api/v1/keys/generate [get]
func KeyValidationHandler ¶ added in v0.4.12
func KeyValidationHandler(w http.ResponseWriter, r *http.Request)
KeyValidationHandler validates any key type (hex, npub, or nsec)
@Summary Validate key @Description Reports whether the supplied string is a well-formed key, and what type (hex, npub, nsec). Does not distinguish public from private when given raw hex. @Tags client-keys @Produce json @Param key path string true "Key to validate" @Success 200 {object} KeyValidationResponse @Failure 400 {object} map[string]string "Key parameter required" @Failure 405 {string} string "Method not allowed" @Router /api/v1/keys/validate/{key} [get]
func LoginHandler ¶ added in v0.4.1
func LoginHandler(w http.ResponseWriter, r *http.Request)
LoginHandler handles user login requests via API Initializes user by fetching mailboxes, setting app relays, getting metadata from outboxes, caching the data, and creating session with appropriate signing capabilities
@Summary Log in @Description Creates a session for the given pubkey. Fetches mailboxes and metadata from outbox relays as a side effect. Set `requestedMode=write` and provide a signing method to enable event publishing. @Tags client-auth @Accept json @Produce json @Param body body session.SessionInitRequest true "Login parameters" @Success 200 {object} session.Response @Failure 400 {object} session.Response "Invalid request" @Failure 405 {string} string "Method not allowed" @Failure 500 {object} session.Response "Failed to create session" @Router /api/v1/auth/login [post]
func LogoutHandler ¶ added in v0.4.1
func LogoutHandler(w http.ResponseWriter, r *http.Request)
LogoutHandler handles user logout requests via API
@Summary Log out @Description Clears the active session cookie. Idempotent — succeeds even if no session was active. @Tags client-auth @Produce json @Success 200 {object} map[string]interface{} @Failure 405 {string} string "Method not allowed" @Router /api/v1/auth/logout [post]
func Nip19DecodeHandler ¶ added in v0.5.0
func Nip19DecodeHandler(w http.ResponseWriter, r *http.Request)
Nip19DecodeHandler decodes NIP-19 bech32 entities (npub, note, nprofile, nevent, naddr) Accepts both GET (URL path) and POST (JSON body) requests to handle long entities
@Summary Decode NIP-19 entity @Description Decodes any NIP-19 bech32 entity (npub, nsec, note, nprofile, nevent, naddr). POST accepts entities too long for a URL path. @Tags client-keys @Accept json @Produce json @Param entity path string false "NIP-19 entity (GET path form)" @Param body body Nip19DecodeRequest false "NIP-19 entity (POST body form)" @Success 200 {object} map[string]interface{} @Failure 400 {object} map[string]string "Invalid entity" @Failure 405 {string} string "Method not allowed" @Router /api/v1/keys/decode/nip19/{entity} [get]
func PingHandler ¶ added in v0.4.12
func PingHandler(w http.ResponseWriter, r *http.Request)
PingHandler pings any relay and returns response time and connection status Now supports domain-in-path with auto ws/wss detection Usage: GET /api/v1/ping/relay.damus.io
@Summary Ping a relay @Description Opens a WebSocket to the given relay and reports the dial latency. Tries `wss://` first, falls back to `ws://`. @Tags client-relays @Produce json @Param domain path string true "Relay domain (no scheme)" @Success 200 {object} map[string]interface{} @Failure 400 {object} map[string]string "Missing domain" @Failure 405 {string} string "Method not allowed" @Router /api/v1/ping/{domain} [get]
func PrivateKeyConversionHandler ¶ added in v0.4.12
func PrivateKeyConversionHandler(w http.ResponseWriter, r *http.Request)
PrivateKeyConversionHandler converts between hex and nsec formats
@Summary Convert private key @Description Converts the supplied private key between hex and nsec. Detects direction from the prefix. @Tags client-keys @Produce json @Param key path string true "Private key (hex or nsec)" @Success 200 {object} map[string]string @Failure 400 {object} map[string]string "Invalid key" @Failure 405 {string} string "Method not allowed" @Router /api/v1/keys/convert/private/{key} [get]
func PublicKeyConversionHandler ¶ added in v0.4.12
func PublicKeyConversionHandler(w http.ResponseWriter, r *http.Request)
PublicKeyConversionHandler converts between hex and npub formats
@Summary Convert public key @Description Converts the supplied public key between hex and npub. Detects direction from the prefix. @Tags client-keys @Produce json @Param key path string true "Public key (hex or npub)" @Success 200 {object} map[string]string @Failure 400 {object} map[string]string "Invalid key" @Failure 405 {string} string "Method not allowed" @Router /api/v1/keys/convert/public/{key} [get]
func PublishEventHandler ¶ added in v0.4.1
func PublishEventHandler(w http.ResponseWriter, r *http.Request)
PublishEventHandler handles event publishing requests
@Summary Publish event @Description Builds, signs (server-side using the supplied private key), and broadcasts a Nostr event to the user's outbox relays plus any extras specified in `relays`. @Tags client-events @Accept json @Produce json @Param body body PublishEventRequest true "Event to publish" @Success 200 {object} PublishEventResponse @Failure 400 {string} string "Invalid request body" @Failure 401 {string} string "Authentication required" @Failure 405 {string} string "Method not allowed" @Failure 500 {object} PublishEventResponse "Publish failed" @Router /api/v1/publish [post]
func QueryEventsHandler ¶ added in v0.4.1
func QueryEventsHandler(w http.ResponseWriter, r *http.Request)
QueryEventsHandler handles event querying using core client
@Summary Query events @Description Issues a Nostr REQ to the connected relays with the filter built from query params. Returns deduplicated, time-sorted events. Caps results at 500 by default. @Tags client-events @Produce json @Param authors query []string false "Pubkey filter (repeatable)" collectionFormat(multi) @Param kinds query []int false "Kind filter (repeatable)" collectionFormat(multi) @Param ids query []string false "Event id filter (repeatable)" collectionFormat(multi) @Param since query int false "created_at lower bound (Unix seconds)" @Param until query int false "created_at upper bound (Unix seconds)" @Param limit query int false "Max events to return" @Success 200 {object} map[string]interface{} @Failure 400 {string} string "Invalid query parameters" @Failure 404 {string} string "Event not found (only when querying a single id)" @Failure 503 {string} string "No relay connections available" @Router /api/v1/events/query [get]
func RefreshCacheHandler ¶ added in v0.4.1
func RefreshCacheHandler(w http.ResponseWriter, r *http.Request)
RefreshCacheHandler manually refreshes cache for the current user
@Summary Force cache refresh @Description Clears and rebuilds the cached user data from outbox relays. Useful after profile updates. @Tags client-cache @Produce json @Success 200 {object} map[string]interface{} @Failure 401 {string} string "User not logged in" @Failure 405 {string} string "Method not allowed" @Failure 500 {string} string "Failed to refresh cache" @Router /api/v1/cache/refresh [post]
Types ¶
type ClientRelaysResponse ¶ added in v0.4.12
type ClientRelaysResponse struct {
Relays []RelayStatus `json:"relays"`
Count int `json:"count"`
}
ClientRelaysResponse represents the response for client relays
type KeyGenerationResponse ¶ added in v0.4.12
type KeyGenerationResponse struct {
PrivateKey string `json:"private_key,omitempty"` // hex format
PublicKey string `json:"public_key,omitempty"` // hex format
Nsec string `json:"nsec,omitempty"` // bech32 format
Npub string `json:"npub,omitempty"` // bech32 format
Error string `json:"error,omitempty"`
}
KeyGenerationResponse represents the response structure for key generation
type KeyValidationResponse ¶ added in v0.4.12
type KeyValidationResponse struct {
Valid bool `json:"valid"`
Type string `json:"type"`
Error string `json:"error,omitempty"`
}
KeyValidationResponse represents the response structure for key validation
type Nip19DecodeRequest ¶ added in v0.5.0
type Nip19DecodeRequest struct {
Entity string `json:"entity"`
}
Nip19DecodeRequest represents the request body for NIP-19 decoding
type PublishEventRequest ¶ added in v0.4.1
type PublishEventRequest struct {
Kind int `json:"kind"`
Content string `json:"content"`
Tags [][]string `json:"tags,omitempty"`
PrivateKey string `json:"privateKey,omitempty"`
Relays []string `json:"relays,omitempty"`
}
PublishEventRequest represents the request structure for publishing events
type PublishEventResponse ¶ added in v0.4.1
type PublishEventResponse struct {
Success bool `json:"success"`
EventID string `json:"eventId,omitempty"`
Event *nostr.Event `json:"event,omitempty"`
Results []core.BroadcastResult `json:"results"`
Summary core.BroadcastSummary `json:"summary"`
Error string `json:"error,omitempty"`
}
PublishEventResponse represents the response structure for publishing events
type RelayStatus ¶ added in v0.4.12
type RelayStatus struct {
URL string `json:"url"`
Connected bool `json:"connected"`
Status string `json:"status"`
Latency *int64 `json:"latency,omitempty"` // Ping latency in milliseconds
LastChecked time.Time `json:"last_checked"`
Read bool `json:"read"`
Write bool `json:"write"`
AddedAt time.Time `json:"added_at"`
}
RelayStatus represents the status of a relay connection
Source Files