Nostr.Event.UserStatus (Nostr Lib v0.2.1) (event) (nip38) (nip40)

View Source

User Statuses (Kind 30315)

Implements NIP-38 for sharing live user statuses such as what music is playing or current activity (working, hiking, etc.).

Status Types

Two common status types are defined:

  • general - General activity statuses ("Working", "Hiking", etc.)
  • music - Live streaming what you're listening to

Any other status types can be used but are not defined by NIP-38.

Examples

# Create a general status
UserStatus.general("Working on nostr-lib")

# Create a music status with expiration
UserStatus.music("Intergalactic - Beastie Boys",
  url: "spotify:search:Intergalactic%20-%20Beastie%20Boys",
  expiration: DateTime.add(DateTime.utc_now(), 180, :second)
)

# Create a status with link
UserStatus.general("Join my Nostr Nest!",
  url: "https://nostrnests.com/abc123"
)

# Clear a status (empty content)
UserStatus.clear("general")

# Check if expired
UserStatus.expired?(status)

See:

Summary

Types

t()

Functions

clear(status_type, opts \\ [])

Clears a status by creating one with empty content.

coordinates(user_status)

Returns the status's address coordinates for use in a tags.

create(status_type, status, opts \\ [])

Creates a user status event.

expired?(user_status)

Checks if the status has expired.

general(status, opts \\ [])

Creates a general status.

music(status, opts \\ [])

Creates a music status.

parse(event)

Parses a kind 30315 event into a UserStatus struct.

Types

t()

@type t() :: %Nostr.Event.UserStatus{
  address: binary() | nil,
  emojis: %{required(binary()) => binary()},
  event: Nostr.Event.t(),
  expiration: DateTime.t() | nil,
  note: binary() | nil,
  profile: binary() | nil,
  status: binary(),
  status_type: binary(),
  url: binary() | nil
}

Functions

clear(status_type, opts \\ [])

@spec clear(
  binary(),
  keyword()
) :: t()

Clears a status by creating one with empty content.

Examples

UserStatus.clear("general")
UserStatus.clear("music")

coordinates(user_status)

@spec coordinates(t()) :: binary() | nil

Returns the status's address coordinates for use in a tags.

Format: 30315:<pubkey>:<status_type>

Returns nil if pubkey is not set.

create(status_type, status, opts \\ [])

@spec create(binary(), binary(), keyword()) :: t()

Creates a user status event.

Arguments

  • status_type - Status category ("general", "music", or custom)
  • status - Status text content (empty string clears the status)
  • opts - Optional keyword list

Options

  • :url - URL reference (r tag)
  • :profile - Profile pubkey reference (p tag)
  • :note - Event ID reference (e tag)
  • :address - Addressable event coordinates reference (a tag)
  • :expiration - DateTime when status expires (NIP-40)
  • :emojis - Custom emoji map for NIP-30 (e.g., %{"wave" => "https://..."})
  • :pubkey - Author pubkey
  • :created_at - Event timestamp

Examples

UserStatus.create("general", "Working hard!")

UserStatus.create("music", "Song Name - Artist",
  url: "spotify:track:abc123",
  expiration: DateTime.add(DateTime.utc_now(), 240, :second)
)

expired?(user_status)

@spec expired?(t()) :: boolean()

Checks if the status has expired.

Returns false if no expiration is set.

Examples

iex> status = UserStatus.general("test")
iex> UserStatus.expired?(status)
false

general(status, opts \\ [])

@spec general(
  binary(),
  keyword()
) :: t()

Creates a general status.

Convenience function for create("general", status, opts).

Examples

UserStatus.general("Working on nostr-lib")

UserStatus.general("In a meeting",
  expiration: DateTime.add(DateTime.utc_now(), 3600, :second)
)

music(status, opts \\ [])

@spec music(
  binary(),
  keyword()
) :: t()

Creates a music status.

Convenience function for create("music", status, opts).

The expiration should typically be set to when the track stops playing.

Examples

UserStatus.music("Intergalactic - Beastie Boys",
  url: "spotify:search:Intergalactic%20-%20Beastie%20Boys",
  expiration: DateTime.add(DateTime.utc_now(), 180, :second)
)

parse(event)

@spec parse(Nostr.Event.t()) :: t() | {:error, String.t(), Nostr.Event.t()}

Parses a kind 30315 event into a UserStatus struct.